RESTful Web 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 。
|
-i,-输入 | 输入/源目录名。项目文件的位置。
例linux必学的60个命令: |
-o,-输出 | 输出目录名。放置生成的文档的位置。
例: |
-t,-模板 | 使用模板输出文件。您可以创建和使用自己的模板。
例: |
-e,--excludedocx和doc的区别-filters | RegEx-Filter选择不应ideological该分析的文件/目录(可以使用很多-e)。(默认值:[])
示例: |
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使用复杂的模板,该模板支持
查看默json格式转换认演示
创建自己的
你可以创建自己的模板,并使用apiDoc生成的文件api_data.js
,api_proje系统运维工资一般多少ct.js
或JSON仅文件api_data.json
,api_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安装教程简化为所需的内容。parser
worker
filidea安装教程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名称/组名称的列表。未定义的名称将自动显示在最后。
|
模板特定设置
以下设置特定于apiDoc的默认模板。
名称 | 类型 | 描述 |
---|---|---|
模板 | ||
强制语言 | 串 | 禁用浏览器语言自动检测并设置特定的语言环境。 范例: de ,en 。在此处查看可用的语言环境。 |
与比较 | 布尔型 | 启json用与旧版api的比较。默认:true |
withGenerator | 布尔型 | 在页脚输出生成器信息。默认:true |
jQueryAjaxSetup | 目的 | 设置Ajax请求的默认值。 |
aloneDisplay | 布尔型 | 单击菜单标题时,仅在页面上显示该内容。默认json是什么意思:false |
页眉linux重启命令页脚
在您的项目中identical,apidlinux删除文件命令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.json
apiDoc中获取项目的名称,版本和描述。
该文件是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"
* }
*/
文档块以开头/**
和结尾*/
。
本示例描述idea了GET
一种通过用户的来请求用户信idea息的方法id
。
@api {gedocx是什么格式的文件t} /user/:id Request User information
是强制性的,没有@api
apidocumentaryDoc会忽略文档块。
@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
。
在生成的输出中,这两种方法GEidealT
和PUT
都将具有完整的UserNolinux必学的60个命令tFoundError
文档。
要定义继承块,请使用apiDefine
。
要引用一个块,请使用apiUse
。aideologypiGroup
并且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
在每个文档块上都设置版本。
该版本可用于每个块,也可用于继承块。您不必在继承块上更改版本,解析器会自动检查最近的前任版本。
完整的例子
这是一个带有inherit
,versioning
文件和历史文件的复杂示例_apidoc.js
,说明在代码和生成的文档内。
查看示例输出
档案:
- _apidoc.js
- example.js
- apidoc.json
apiDoc-Paramdocuments
结构参数如:
@apiDefine
用于定义可重用的文档块。此块可以包含在常规api文档块中。使用@apiDefiJsonne
使您可以更好地组织复杂的文档,并避免重复的doc重复linux块。
定义的块可以具有所有参数(如@json格式apiPara系统运维工作内容m
)docx是什么格式的文件,其他定义的块除外。
@api
@api {method} path [title]
需要!
如果没有该指示符,则apiDoc解析器将忽略文档记录块。
唯一的例外是由定义的文档块@apideiDefine
,它ideology们系统运维工程师面试问题及答案不是必需的@api
。
用法:@api {get} /user/:id Users unique ID.
名称 | 描述 |
---|---|
方法 | 请求方法名称:DELETE ,GET ,POST ,PUT ,...更多信息维基百科的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标头的参数,例如用于授权。
用法:@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的数字。
可以与大小组合: |
领域 | 栏位名称。 |
[领域] | 带括号的字段名称将变量定义为可选。 |
字段[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: 在@apiurl之前添加前缀: 如果设置了配置参数sampleUrl,则禁用api测试: |
例子:
这会将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
定义的块。如果与@apiVersion
相json文件是干什么的同或最接近的前任产品一起使用,则将包括在内。
用法:@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
*/
有关更多手表版本控制示例。系统运维主要做什么
发表评论