apiDoc入门、通过源代码中的API注释、创建文档(中文版)、安装、运行

API文档

RESTful Web API的内联文档

apiDoc通过源代码中的API注释创建文档。

apiDoc使您能够将版本号附加到API以便您可以轻松跟踪版本之间的更改。

  • 演示版
  • 入门
  • 前言
  • 安装
  • 命令界面
  • GRUNT模块
  • 模板
  • 延伸
  • 配置(apidoc.js系统运维主要做什么on)
  • 页眉页脚
  • 例子
  • 基本的
  • 继承
  • 版本控制
  • 完整示例(一起)
  • apiDoc-Params
  • @api
  • @a系统运维工资一般多少piDefine
  • @api已弃用
  • @api说明
  • @apiErrodocx是什么格式的文件r
  • @apiErrorExample
  • @apiExample
  • @apiGroup
  • @apiHeader
  • @apiHeaderExample
  • @apiIgnore
  • @apiName
  • @apiParam
  • @apiParamExample
  • @apiPermission
  • @api私人
  • @jsonpapiSampleRequest
  • @api成功
  • @apidocx和doc的区别SuccessExample
  • @apiUse
  • @apiVersion

  • 不推荐使用的参数
入门

安装

npm install apidoc -g

apidoc -i myapp/ -o apidoc/ -t mytemplate/

创建dir中所有dock文件的apiDocmyapp/使用dir中idea模板mytemplate/,并将所有输出放入dir中apidoc/

如果没有任何参数,apiDoc将从.cs.dart.erl.go.java.js.php.py.rb.ts当前目录(包括子目录)中的所有文件生成文档,并将输出写入./doc/

命令行界面

显示命令行参数:

apidoc -h

重要参数:

参数 描述
-f,--file-filters RegEx-Filter选择分析的文件(可以使用许多-f)。默认.cs.dart.erl.go.java.js.php.py.rb.tlinuxs

示例(仅解析.js和.tside件):
apidoc -f ".*\\.js$" -f ".*\\.ts$"

-i,-输入 输入/源目录名。项目文件的位置。

linux必学的60个命令
apidoc -i myapp/

-o,-输出 输出目录名。放置生成的文档的位置。

例:
apidoc -o apidoclinux命令/

-t,-模板 使用模板输出文件。您可以创建和使用自己的模板。

例:
apidoc -t mytemplate/

-e,--excludedocx和doc的区别-filters RegEx-Filter选择不应ideological分析的文件/目录(可以使用很多-e)。(默认值:[])

示例:
apidoc -e node_modules

GRUNT模jsonp跨域原理

支持单独的grunt模块,请访问github.com/apidoc/grunt-apidoc
或通过npidem安装:

npm install grunt-apidoc --save-dev

模板

apiDoc包括使用缺省模板车把,自举,RequireJS和jQuery的所生成的输出api_data.js并且api_project.js作为一个HTML页。

默认情况下,生成的apiDoc使用复杂的模板,该模板支持

  • 版本控制:查看您的dockAPI的不同版本linux常用命令
  • 比较:查看两个API版本之间的更改

查看默json格式转换认演示

创建自己的

你可以创建自己的模板,并使用apiDoc生成的文件api_data.jsapi_proje系统运维工资一般多少ct.js或JSON仅文件api_data.jsonapi_project.json

https://github.com/apidoc/alinux必学的60个命令pidoc/tree/master/temjson格式转换plate上查看源代码

延伸

可以使用您linux自己的参数扩展apiDoc(如果您需要的参数不可用)。请查看apidoc / apidoc-core项目中的lib / parsers /,lib / workers /和lib / filters /目录以获取示例。拆分参数数据,使用所有找到的数据处理其他功能,并将数据idea安装教程简化为所需的内容parserworkerfilidea安装教程ter

用法示例:apidoc --parse-fdockilters myFilter=padocx是什么格式的文件thToMyFilter/mjson数据yFil系统运维工程面试问题及答案ter.js

或分叉整个项目并创建请求请求,以使apidocx和doc的区别Doc更好。

配置(apidoc.json)

apidoc.json项目根目录中的可选内容包括有关项目的常用信jsonp跨域原理息,例如标题,简短描述,版本和配置选项(例如页眉/页脚设置或模板特定的选项)。

apidoc.json

{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}

如果您使用package.json(例如在node.js项目中),则所有apidoc.jideason设置也可以完成package.json,只需将其添加到"apidoc": { }ideological数下即可json格式

package.json

{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"apidoc": {
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}
}

apidoc.json的设置

名称 描述
名称 项目名称。
如果apidoc.jsonpjson该字段不存在,则apiDoc尝试从确定值pacidentificationkage.json
项目的版本。jsonp跨域原理
如果apidoc.json该字段不存在,则apiDoc尝试从确定值package.json
描述 项目简介。
系统运维主要做什么apidoc.jslinux常用命令on该字段不存在,则apiDoc尝试从确定值package.json
标题 浏览器标题文系统运维面试题及答案本。
网址 api路径的前缀(端点),例如https:docx和doc的区别//api.github.com/v1
sampleUrl 如果设置,则将显示用于测试api方法(发送请docx是什么格式的文件求)的单。有关更多详细信息,请参见@apiSampleRequest。
标头
标题 包含的header.md文件的导航文本。
(观看页眉/页脚)
文档名称 包含的header.md系统运维主要做什么文件的文件名(markdown-file)。
页脚
标题 包含的footer.md文件的导航文本。
文档名称 包含的linuxfooter.md文件的文件名(markdown文件)。
订购 用于排序输出的api名称/组名称的列。未定义的名称将自动显示在最后。

"order": [
"Error",
"Define",
"PostTitleAndError",
"PostError"
]

模板特定设置

以下设置特定于apiDoc的默认模板。

名称 类型 描述
模板
强制语言 禁用浏览器语言自动检测并设置特定的语言环境。
范例:deen。在此处
查看可用的语言环境。
与比较 布尔型 json用与旧版api的比较。默认:true
withGenerator 布尔型 在页脚输出生成器信息。默认:true
jQueryAjaxSetup 目的 设置Ajax请求的默认值。
aloneDisplay 布尔型 单击菜单标题时,仅在页面上显示该内容。默认json是什么意思false

页眉linux重启命令页脚

在您的项目中identicalapidlinux删除文件命令oc.json您可document以添加页眉和页脚。

标题将在导航中可见。文件名应为降价文本文件。

apiddocx和doc的区别oc.json

{
"header": {
"title": "My own header title",
"filename": "header.md"
},
"footer": {
"title": "My own footer title",
"filename": "footer.md"
}
}

例子

可以doctor异乡人在Speakerdeck.com上找到介绍演示和一个小例子。

基本的

在这个基本示例中,我们有一个小Json项目文件和identify一个apid系统运维包括哪些内容oc.json。

查看示例输出

apidoc.json

{
"name": "example",
"version": "0.1.0",
"description": "A basic apiDoc example"
}

apidoc.jsonapiDoc中获取项目的名称,版本和描述。
该文件是optional(如果需要数据,则取决于模板)。

example.js

/**
* @api {get} /user/:id Request User information
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname  Lastname of the User.
*
* @apiSuccessExample Success-Response:
*     HTTP/1.1 200 OK
*     {
*       "firstname": "John",
*       "lastname": "Doe"
*     }
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
*     HTTP/1.1 404 Not Found
*     {
*       "error": "UserNotFound"
*     }
*/

文档块以开头/**和结尾*/

本示例描述ideaGET一种通过用户的来请求用户idea息的方法id

@api {gedocx是什么格式的文件t} /user/:id Request User information是强制性的,没有@apiapidocumentaryDoc会忽略文档块。

@apiName必须是唯一名称,并系统运维工作内容且应始终使用。
格式:linux必学的60个命令方法+路径(例如,获取+用户)

@apiGroup应该始终使用,并用于将相关的APIjson组合在一起。

所有其他字段都是可选的,请在apiDoc-Params下查看其描述。

继承

使jsonp跨域原理用继承,您可以定义文档的可重用代码段。

查看示例输出

apidoc.json

{
"name": "example-inherit",
"version": "0.1.0",
"description": "apiDoc inherit example"
}

example.js

/**
* @apiDefine UserNotFoundError
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
*     HTTP/1.1 404 Not Found
*     {
*       "error": "UserNotFound"
*     }
*/
/**
* @api {get} /user/:id Request User information
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname  Lastname of the User.
*
* @apiSuccessExample Success-Response:
*     HTTP/1.1 200 OK
*     {
*       "firstname": "John",
*       "lastname": "Doe"
*     }
*
* @apiUse UserNotFoundError
*/
/**
* @api {put} /user/ Modify User information
* @apiName PutUser
* @apiGroup User
*
* @apiParam {Number} id          Users unique ID.
* @apiParam {String} [firstname] Firstname of the User.
* @apiParam {String} [lastname]  Lastname of the User.
*
* @apiSuccessExample Success-Response:
*     HTTP/1.1 200 OK
*
* @apiUse UserNotFoundError
*/

在此示例中,使用UserNotFoundError定义了名为的块@apdoctrineiDefine
该块可以与一identification起使用多次@apiUse UserNotFoundError

在生成的输出中,这两种方法GEidealTPUT都将具有完整的UserNolinux必学的60个命令tFoundError文档。

要定义继承块,请使用apiDefine
要引用一个块,请使用apiUseaideologypiGroup并且apiPermissidoctrineon使用命令来(但在上下文中)不继承参数,仅继承标题和描述(与apiVersion结合使用)。

继承仅适用于1个父级,更多级别将使linux删除文件命令内联代码不可读,并且更改identification确实非常复杂。

版本ideological控制

apiDoc提供的一项有用功能document是能够维护所有先前版本和最新版本的API文档。这样就可以将方法版本与其doctrine先前版本进行比较。因此,Frontend Developer可以简单地ideology查看已更改的内系统运维工资一般多少容并相应地更新其代码。

查看示例输docx和doc的区别

在示例中,单击选择框(主版本)的右上角,然后选择Compare all with predecessor

  • 主导航用绿色条标记所有已更改的方法。
  • 每种方法都显示出与其前任相比的实际差异。
  • 绿色标记添加的内容(在这种情况下,标题文本已更改,字段registered已添加)。
  • 红色标记已删除的内容。

您可以将主版本(右上方)更改为以前的版本,然后将较旧的方linux创建文件法与以前的方法进行比较。

apidoc.jsonjson

{
"name": "example-versioning",
"version": "0.2.0",
"description": "apiDoc versioning example"
}

为了避免API文档随时间变化而导致代码膨胀,建议使用名为的单独历史doctors记录文件_apidocdocx是什么格式的文件.js。在更改文档栏之前,请将旧文档复制到该文件,apiDoc将自动包括历史信息。

_apidoc.js

/**
* @api {get} /user/:id Get User information
* @apiVersion 0.1.0
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname  Lastname of the User.
*
* @apiSuccessExample Success-Response:
*     HTTP/1.1 200 OK
*     {
*       "firstname": "John",
*       "lastname": "Doe"
*     }
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
*     HTTP/1.1 404 Not Found
*     {
*       "error": "UserNotFound"
*     }
*/

example.js(您当前的项目文件)

/**
* @api {get} /user/:id Get User information and Date of Registration.
* @apiVersion 0.2.0
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname  Firstname of the User.
* @apiSuccess {String} lastname   Lastname of the User.
* @apiSuccess {Date}   registered Date of Registration.
*
* @apiSuccessExample Success-Response:
*     HTTP/1.1 200 OK
*     {
*       "firstname": "John",
*       "lastname": "Doe"
*     }
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
*     HTTP/1.1 404 Not Found
*     {
*       "error": "UserNotFound"
*     }
*/

重要的是@apiVersion在每个文档块上都设置版本。

该版本可用于每个块,也可用于继承块。您不必在继承块上更改版本,解析器会自动检查最近的前任版本。

完整的例子

这是一个带有inheritversioning文件和历史文件的复杂示例_apidoc.js,说明在代码和生成的文档内。

查看示例输出

档案:

  • _apidoc.js
  • example.js
  • apidoc.json

apiDoc-Paramdocuments

结构参数如:

  • @apiDefine

用于定义可重用的文档块。此块可以包含在常规api文档块中。使用@apiDefiJsonne使您可以更好地组织复杂的文档,并避免重复的doc重复linux块。

定义的块可以具有所有参数(如@json格式apiPara系统运维工作内容mdocx是什么格式的文件其他定义的块除外

@api

@api {method} path [title]

需要!

如果没有该指示符,则apiDoc解析器将忽略文档记录块。

唯一的例外是由定义的文档块@apideiDefine,它ideology系统运维工程师面试问题及答案不是必需的@api

用法:@api {get} /user/:id Users unique ID.

名称 描述
方法 请求方法名称:DELETEGETPOSTPUT,...
更多信息维基百科的HTTP-Requesdocxt_methods
路径 请求路径。
标题可选的 简短标题。(用于导航和文章标题)

例:

/**
* @api {get} /user/:id
*/

@apiDefine

@apiDefine name [title]
[description]

定义要嵌入到ide文档块linux系统@api或api函数之类的文档模块@apiPermission

@apiDefine每个方块只能使用一次

通过使用系统运维工程@apiUse已定义的块,将导入该块,或使系统运维主要做什么用名称和标题和说明。

ide法:@apiDefine MyError

名称 描述
名称 块/值的唯一名称。可以定义
不同的相同名称@apiVersion
标题可选的 简短标题。仅用于命名函数,例如@apiPermission@apiParam (name)
描述可选的 详细说明从下一行开始,可以使用多行。仅用于命系统运维工程师面试问题及答案名函数,如@apiPermission

例:

/**
* @apiDefine MyError
* @apiError UserNotFound The <code>id</code> of the User was not found.
*/
/**
* @api {get} /user/:id
* @apiUse MyError
*/
/**
* @apiDefine admin User access only
* This optional description belong to to the group admin.
*/
/**
* @api {get} /user/:id
* @apiPermission admin
*/

有关更多详细信息,请参见继承示例。

@api已弃用

@apiDeprecated [text]

将API方法标记为不推荐使用

用法:@apiDeprecated use now (#Group:Name).

名称 描述
系统运维的主要任务 多行文字。linux命令

例:

/**
* @apiDeprecated
*/
/**
* @apiDeprecated use now (#Group:Name).
*
* Example: to set a link to the GetDetails method of your group User
* write (#User:GetDetails)
*/

@api说明

@apiDescription text

API方法的详细说明。

用法:@apiDescription This is the Description.

名称 描述
文本 多行linux操作系统基础知识描述文字。

例:

/**
* @apiDescription This is the Description.
* It is multiline capable.
*
* Last line of Description.
*/

@apiError

@apiError [(group)] [{type}] field [description]

错误返回参数。

用法:@apiError UserNotFound

名称 描述
(组linux可选的 linux必学的60个命令有参数将按此名称分组。
如果没有组,Error 4xx则设置默认值。
您可以使系统运维工程师面试问题及答案用@apiDefine设置标题和描述。
{类型}可选的 返回类型,例如{Boo系统运维工作内容lean}{Number}{String}{Object}{String[]}字符串数组json),...
领域 返回标识符(返回的错误代码)。
描述可选的jsonp 字段说明。

例:

/**
* @api {get} /user/:id
* @apiError UserNotFound The <code>id</code> of the User was not found.
*/

@apiErrorExample

@apiErrorExample [{type}] [title]
example

错误返回消息的示例,以预格式化的代码输出。

用法:@apiErrorExample {json} Error-Resdocponse:
Thijson格式s is an example.

名称 描述
类型可选的 响应格式。
标题可选的 该示例的简短标题。
详细的例子,多行功能linux创建文件

例:

/**
* @api {get} /user/:id
* @apiErrorExample {json} Error-Response:
*     HTTP/1.1 404 Not Found
*     {
*       "error": "UserNotFound"
*     }
*/

@apiExample

@apiExample [{type}] title
example

API方法使用示例。输出为预格式化的代json码。

在端点描述的开头,将其ideal用作完整示例。

用法:@apiExample {js} Example usage:
This is an example.

linux操作系统基础知识 描述
类型可选的 代码语言。
标题 该示例的简短标题。
详细的例子,多行功能identical

例:

/**
* @api {get} /user/:id
* @apiExample {curl} Example usage:
*     curl -i http://localhost/user/4711
*/

@apiGdocumentroup

@apiGroup name

应该始终使用。

定义方法文档块属于哪个组。组将用于生成的输出中的主导航。不需要结构定义@apiGjson数据roup

用法:@apiGroup User

名称 描述
名称 组名。也用作导航标题。

例:

/**
* @api {get} /user/:id
* @apiGroup User
*/

@apiHeader

@apiHeader [(group)] [{type}] [field=defaultValue] [description]

描述传递给您的Ajsonp跨域原理PI标头的参数,例如用于授权。

与@apiParam类似操作,仅输出在参数之上。

用法:@apiHeader (MyHeaderGroup) {String} authorization Authorization value.

名称 描述docx和doc的区别
(组)可选的 所有参数将按系统运维工程师面试问题及答案此名称分组。
如果没有组,Parameter则设置默认值。
您可以使用@apiDefine设置标题和描述。doctors
{类型}可选的 参数类型,例如{Boolean}{Number}{String}{Object}identification{Strlinuxinlinux是什么操作系统g[]}字符串数组),...
领域 变量名称。
[领域] 带括号的字段名称将变量定义为可选。
=默认值可选的 doc数默认值。
描述可选的 字段说明。

例子:

/**
* @api {get} /user/:id
* @apiHeader {String} access-key Users unique access-key.
*/

@apiHeaderEdocxxample

@apiHeaderExample [{type}] [title]
example

参数请求示例。

用法:@apiHeaderExample {ideologyjson} Request-Example:
{ "content": "This is an example content" }

名称 描述
类型可选的 请求格式。
标题可选的 该示例的简短标题。
详细的例子,多行功能。

例:

/**
* @api {get} /user/:id
* @apiHeaderExample {json} Header-Example:
*     {
*       "Accept-Encoding": "Accept-Encoding: gzip, deflate"
*     }
*/

@apiIgnore

@apiIgnore [hint]

将其放系统运维面试题及答案在一个块的顶部。

@apiIgnore不会解析的块。如果您在源代码中留下了过时的或未完成的方法,并且不想将其docx和doc的区别发布到文档中,则这很有用

用法:@apiIgnor系统运维工作内容e Not finished Method

名称 描述
暗示可选的 有关为何应忽略linux此块的简短信息。

例:

/**
* @apiIgnore Not finished Method
* @api {get} /user/:id
*/

@apiName

@apiName name

应该始终使用。

定义方法文档块的名称。名称将用于生成的输出中的子导航。不需要结构定义@apiNlinux系统ame

系统/运维法:@apiName GetUser

名称 描述
名称 方法的唯一名称。@apiVersion可以定义不同的相同名称。
格式:方法linux创建文件+路径(例如Get + Userdocx
),只有建议,您可以根据需要命名。
也用作导航标题。

例:

/**
* @api {get} /user/:id
* @apiName GetUser
*/

@apiParam

@apiParam [(group)] [{type}] [field=defaultValue] [description]

描述传递给您的API方法的参数。

用法:@apiParalinux删除文件命令m (MyGroup) {Number} id Usersjson格式 unique ID.

对于嵌套参数,请使用方括号符号([])。

名称 描述
(组json格式可选的 所有参数将按此名称分组。
如果没有组,Parameter则设置默认值。
您可以使用@apiDefine设置标题和描述。
{类型}可选的 参数类型,例如{Boolean}{Number}{String}{Object}{Slinux命令tring[]}(字符串数组),...
{type {size}}可选的 有关变量大小的信息。
{string{..系统运维工资一般多少5}}最多5个字符的字符串。
{string{2..5}}最小的字符串2个字符,最多5个字符。
{number{100-999}}100到999之间的数字。
{type = allowedValues}可选的 有关变量的允许值的信息。
{string="small"}一个只能包含单词“ small”(常量)的字符串。
{string="small","huge"}一个可以包含单词“ smjson解析all”或“ huge”的字符串。
{number=1,2,3,99}一个允许值为1、2、3和99的数字。

可以与大小组合:
{string {..5}="small","huge"}一个字符串,最多包含5个字符,并且仅包含单ideology词“ small”json格式转换或“ huge”。

领域 栏位名称。
[领域] 带括号的字段名称将变量定义为可选。
字段[nestedField] 强制嵌套字段。
=默认值可选的 参数默认值。
描述可选的 字段说明。

例子:

/**
* @api {get} /user/:id
* @apiParam {Number} id Users unique ID.
*/
/**
* @api {post} /user/
* @apiParam {String} [firstname]       Optional Firstname of the User.
* @apiParam {String} lastname          Mandatory Lastname.
* @apiParam {String} country="DE"      Mandatory with default value "DE".
* @apiParam {Number} [age=18]          Optional Age with default 18.
*
* @apiParam (Login) {String} pass      Only logged in users can post this.
*                                      In generated documentation a separate
*                                      "Login" Block will be generated.
*
* @apiParam {Object} [address]         Optional nested address object.
* @apiParam {String} [address[street]] Optional street and number.
* @apiParam {String} [address[zip]]    Optional zip code.
* @apiParam {String} [address[city]]   Optional city.
*/

@apiParamExample

@apiParamExample [{type}] [title]
example

参数请求示linux删除文件命令例。

用法:@apiParamExample {json} Request-linux是什么操作系统Example:
{ "content": "This is an example content" }

名称 描述
类型可选的 请求格式。
标题可选的 该示例的简短标题。
详细的例子,多行功能。

例:

/**
* @api {get} /user/:id
* @apiParamExample {json} Request-Example:
*     {
*       "id": 4711
*     }
*/

@apiPdoctor异乡人ermission

@apiPermission name

输出权限名称。如果名称是@apiDefine在生成的文档中定义的,则包括其他系统运维面试题及答案标题和描述。

用法:@apiPermission admin

名称 描述
名称 权限的唯一名称。

例:

/**
* @api {get} /user/:id
* @apiPermission none
*/

@api私人

@apiPrivate

将API定义为私有API,以允许jsonp创建jsonp两个API规范文档:一个排除私有API,另documentary一个包括私有API。

用法:@apiPrivate

用于排除/包括私有API的命令行用法:--private false|系统运维工作内容true

例:

/**
* @api {get} /user/:id
* @apiPrivate
*/

@apiSampleRequest

@apiSampleRequest url

将此参数与apidoc.json配置参数sampleUrl结合使用。

如果sampjsonleUrl设置为,则所有方法都将具有api测试表单(将附加@api的端点)。
如果不使用sampleUrl,则仅有的方法@apiSampleRequest将具有形式。

如果@apiSampleRequest url在方法块中设置了if,则该网址将用于请求(当它以http开头时,它将覆盖sampleUrl)。

如果sampleUrl设置为if并且您不想要带有测试表单的方法,则将其添加@apiSampleRequest off到documentation块中。

用法:@apiSampleRejson格式quest http://test.github.com

linux重启命令 描述
网址 网址到您的测试API服务器。

覆盖配置参数sampleUrl并附ide0sgrtsts另类加@apiurl:
@系统运维的主要任务apiSamideapleRequest hlinux系统ttp://www.example.com

在@apiurl之前添加前缀:
@apiSampleRequest /mlinux操作系统基础知识y_test_path

如果设置了配置参数sampleUrl,则禁用api测试:
@apiSampleRequest off

例子:

这会将api请求发送到http://json文件是干什么的api.github.com/user/linux常用命令:id

Configuration parameter sampleUrl: "http://api.github.com"
/**
* @api {get} /user/:id
*/

这会将api请求发送到http://test.github.com/some_path/user/:id。
它将覆盖sampleUrl。

Configuration parameter sampleUrl: "http://api.github.com"
/**
* @api {get} /user/:id
* @apiSampleRequest http://test.github.com/some_path/
*/

这会将api请求发送到http:identify/json格式/api.github.com/test/user/:iddoc
它扩展了samdocumentpleUrdocumentl。

Configuration parameter sampleUrl: "http://api.github.com"
/**
* @api {get} /user/:id
* @apiSampleRequest /test
*/

这将禁用此api方法的api请求。

Configuration parameter sampleUrl: "http://api.github.com"
/**
* @api {get} /user/:id
* @apiSampleRequest off
*/

这会将api请求发document送到http://api.github.系统运维主要做什么com/some_path/user/:id
。由于未设置sampleUrl,因此仅激活此json格式方法的请求。

Configuration parameter sampleUrl is not set
/**
* @api {get} /user/:id
* @apiSampleRequest http://api.github.com/some_path/
*/

@api成功

@apiSuccess [(group)] [{type}] field [description]

成功返回参数。

用法:@a系统运维面试题及答案piSuccess {String} firstname Firstname of the User.

名称 描述
(组linux可选的 所有参数系统运维工作内容将按此名称分组。
如果没有组,Success 200则设置默认值。
您可以使用@apiDefine设置标题linux常用命令和描述。
{类型}可选的 返回类型,例如{Boolean}{Number}{String}{Object}{String[]}(字符串数组),...
领域 返回标识符(返回成功代码)。
描述可选的 字段说明。

例:

/**
* @api {get} /user/:id
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname  Lastname of the User.
*/

doctors示例(group),@apiSuccessTitle上的更多组示例:

/**
* @api {get} /user/:id
* @apiSuccess (200) {String} firstname Firstname of the User.
* @apiSuccess (200) {String} lastname  Lastname of the User.
*/

对象示例:

/**
* @api {get} /user/:id
* @apiSuccess {Boolean} active        Specify if the account is active.
* @apiSuccess {Object}  profile       User profile information.
* @apiSuccess {Number}  profile.age   Users age.
* @apiSuccess {String}  profile.image Avatar-Image.
*/

数组示例:

/**
* @api {get} /users
* @apiSuccess {Object[]} profiles       List of user profiles.
* @apiSuccess {Number}   profiles.age   Users age.
* @apiSuccess {String}   profiles.image Avatar-Image.
*/

@apiSuccdockessExample

@apiSuccessExample [{type}] [title]
example

成功返回消息的示例,以预格式化的代码输出。

用法:@apiSuccessideasExample {jsolinux重启命令n} Success-Response:
{ "content": "This is an example content" }

名称 描述
类型可选的 响应格式。
系统运维包括哪些内容可选的 该示例的简短标题。
详细的ideal例子,多行功能。

例:

/**
* @api {get} /user/:id
* @apiSuccessExample {json} Success-Response:
*     HTTP/1.1 200 OK
*     {
*       "firstname": "John",
*       "lastname": "Doe"
*     }
*/

@apiUse

@apiUse name

包括一个带有@apiDefine定义的块。如果与@apiVersionjson文件是干什么的同或最接近的前任产品一起使用,则将包括在内。

用法:@apiUse MySjsonp跨域原理uccess

名称 描述
名称 定义块的名称。

例:

/**
* @apiDefine MySuccess
* @apiSuccess {string} firstname The users firstname.
* @apiSuccess {number} age The users age.
*/
/**
* @api {get} /user/:id
* @apiUse MySuccess
*/

@apiVersion

@apiVersion version

设置文档块的版本。版本也可以在中使用@apiDefine系统运维工资一般多少

具有相同组和名称但不同版本的块可以在生成的输出中进行比较,Json因此您或前端开发人员可以追溯自上一个版本以来API中的更改。

用法:@apiVersion 1.6.2

名称 描述
支持简单版本控制(major.minor.patch)。有关语义版本规范(SemVer)的更多信息。

例:

/**
* @api {get} /user/:id
* @apiVersion 1.6.2
*/

有关更多手表版本控制示例。系统运维主要做什么