Apidoc安装与使用
什么是apidoc
apidoc可以根据代码注释生成web api文档，支持大部分主流语言java javascript php coffeescript erlang perl python ruby go...，相对而言，web接口的注释维护起来更加方便，不需要额外再维护一份文档。
apidoc从注释生成静态html网页文档，不仅支持项目版本号，还支持api版本号。
apidoc安装
需要先安装npm包管理器,使用npm命令安装
npm install apidoc -g
检查是否安装成功
apidoc -h
apidoc的使用
如何运行
以下命令，表示从myapp/目录读取api注释信息，在apidoc/目录生成文档说明，指定显示模板mytemplate/
apidoc默认有一套模板用来呈现页面效果，如无特殊需求，可以不指定
apidoc -i myapp/ -o apidoc/ -t mytemplate/
若不使用任何参数，将会使用当前目录（包含子目录下的）所有.cs .dart .erl .go .java .js .php .py .rb .ts后缀的文件来生成，并保存至./doc目录下
一些重要的命令行参数说明：
-f, --file-filters RegEx-Filter to select files that should be parsed (many -f can be used). Default .cs .dart .erl .go .java .js .php .py .rb .ts.
Example (parse only .js and .ts files):
apidoc -f ".*\\.js$" -f ".*\\.ts$"
-i, --input Input / source dirname. Location of your project files.
Example:
apidoc -i myapp/
-o, --output Output dirname. Location where to put to generated documentation.
Example:
apidoc -o apidoc/
-t, --template Use template for output files. You can create and use your own template.
Example:
apidoc -t mytemplate/
配置(apidoc.json)
可在项目的根目录，包含一个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.json的配置可以在package.json中完成，仅仅只需要把它们置于”apidoc”: { }中
示例:
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"apidoc": {
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}
}
apidoc.json的设置
Settings for apidoc.json
name Name of your project.
If no apidoc.json with the field exists, then apiDoc try to determine the the value from package.json.
version Version of your project.
If no apidoc.json with the field exists, then apiDoc try to determine the the value from package.json.
description Introduction of your project.
If no apidoc.json with the field exists, then apiDoc try to determine the the value from package.json.
title Browser title text.
url Prefix for api path (endpoints), e.g. https://api.github.com/v1
sampleUrl If set, a form to test an api method (send a request) will be visible. See @apiSampleRequest for more details.
header
title Navigation text for the included header.md file.
(watch Header / Footer)
filename Filename (markdown-file) for the included header.md file.
footer
title Navigation text for the included footer.md file.
filename Filename (markdown-file) for the included footer.md file.
order A list of api-names / group-names for ordering the output. Not defined names are automatically displayed last.
"order": [
"Error",
"Define",
"PostTitleAndError",
"PostError"
]
使用案例
apidoc.json
{
"name": "example",
"version": "0.1.0",
"description": "A basic apiDoc example"
}
一个文档注释以/**开头，**/结尾。
以下描述了通过GET方式，请求User信息，通过id参数。
其中@api {get} /user/:id Request User information是必需的，如果没有@api参数，则将忽略这个注释
@apiName是一个唯一的名称
@apiGroup表示属于哪个组
其他的参数都是可选的
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"
* }
*/
继承特性
通过继承，可以定义描述文档，被多次使用，如以下例子 通过@apiDefine定义了一个块注释UserNotFoundError，该注释可以被多次使用，通过@apiUse UserNotFoundError方式使用
/**
* @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
*/
版本控制
好的特点是保持以前定义的文档块。可以通过比较的方式在不同的版本之前进行显示想应的改动。前端开发人员可以简单地看到什么样的改变和修改他们的代码。
通过 @apiVersion注释，可以生成不同版本的对比信息
历史版本的文件，如可以取名为_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"
* }
*/
注释块中的参数说明 apiDoc-Params
@api (必需)
没有该注释，将自动忽略该注释块(特例,对于使用@apiDefine的注释块，不需要@api参数)
@api {method} path [title]
method Request method name: DELETE, GET, POST, PUT, ...
More info Wikipedia HTTP-Request_methods
path Request Path.
title optional A short title. (used for navigation and article header)
Usage: @api {get} /user/:id Users unique ID.
example:
/**
* @api {get} /user/:id
*/
@apiDefine
定义一个块注释，可以被其他块注释继承使用，每个块注释中，只能使用一次@apiDeine
@apiDefine name [title] [description]
name Unique name for the block / value.
Same name with different @apiVersion can be defined.
title optional A short title. Only used for named functions like @apiPermission or @apiParam (name).
description optional Detailed Description start at the next line, multiple lines can be used. Only used for named functions like @apiPermission.
Usage: @apiDefine MyError
Example:
/**
* @apiDefine MyError
* @apiError UserNotFound The <code>id</code> of the User was not found.
*/
/**
* @api {get} /user/:id
* @apiUse MyError
*/
@apiDescription
对该api接口的描述
@apiDescription text
Usage: @apiDescription This is the Description.
Example:
/**
* @apiDescription This is the Description.
* It is multiline capable.
*
* Last line of Description.
*/
@apiError
定义错误信息
@apiError [(group)] [{type}] field [description]
(group) optional All parameters will be grouped by this name.
Without a group, the default Error 4xx is set.
You can set a title and description with @apiDefine.
{type} optional Return type, e.g. {Boolean}, {Number}, {String}, {Object}, {String[]} (array of strings), ...
field Return Identifier (returned error code).
description optional Description of the field.
Usage: @apiError UserNotFound
Example:
/**
* @api {get} /user/:id
* @apiError UserNotFound The <code>id</code> of the User was not found.
*/
@apiErrorExample
定义错误输出demo
@apiErrorExample [{type}] [title]
example
type optional Response format.
title optional Short title for the example.
example Detailed example, multilines capable.
Usage: @apiErrorExample {json} Error-Response:
This is an example.
Example:
/**
* @api {get} /user/:id
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
@apiExample
api接口的使用demo
@apiExample [{type}] title
example
type optional Code language.
title Short title for the example.
example Detailed example, multilines capable.
Usage: @apiExample {js} Example usage:
This is an example.
Example:
/**
* @api {get} /user/:id
* @apiExample {curl} Example usage:
* curl -i http://localhost/user/4711
*/
@apiGroup
定义一个组
@apiGroup name
Usage: @apiGroup User
Example:
/**
* @api {get} /user/:id
* @apiGroup User
*/
@apiHeader
定义api的请求header信息,如授权 Authorization.
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
Usage: @apiHeader (MyHeaderGroup) {String} authorization Authorization value.
Examples:
/**
* @api {get} /user/:id
* @apiHeader {String} access-key Users unique access-key.
*/
@apiHeaderExample
api的header请求demo
@apiHeaderExample [{type}] [title]
example
Usage: @apiHeaderExample {json} Request-Example:
{ "content": "This is an example content" }
Example:
/**
* @api {get} /user/:id
* @apiHeaderExample {json} Header-Example:
* {
* "Accept-Encoding": "Accept-Encoding: gzip, deflate"
* }
*/
@apiIgnore
置于注释块的顶部，表示暂时忽略该注释块
@apiIgnore [hint]
Usage: @apiIgnore Not finished Method
Example:
/**
* @apiIgnore Not finished Method
* @api {get} /user/:id
*/
@apiName
api的名称
@apiName name
Usage: @apiName GetUser
Example:
/**
* @api {get} /user/:id
* @apiName GetUser
*/
@apiParam
api参数
@apiParam [(group)] [{type}] [field=defaultValue] [description]
(group) optional All parameters will be grouped by this name.
Without a group, the default Parameter is set.
You can set a title and description with @apiDefine.
{type}optional Parameter type, e.g. {Boolean}, {Number}, {String}, {Object}, {String[]} (array of strings), ...
{type{size}}optional Information about the size of the variable.
{string{..5}} a string that has max 5 chars.
{string{2..5}} a string that has min. 2 chars and max 5 chars.
{number{100-999}} a number between 100 and 999.
{type=allowedValues}optional Information about allowed values of the variable.
{string="small"} a string that can only contain the word "small" (a constant).
{string="small","huge"} a string that can contain the words "small" or "huge".
{number=1,2,3,99} a number with allowed values of 1, 2, 3 and 99.
Can be combined with size:
{string {..5}="small","huge"} a string that has max 5 chars and only contain the words "small" or "huge".
field Variablename.
[field] Fieldname with brackets define the Variable as optional.
=defaultValueoptional The parameters default value.
descriptionoptional Description of the field.
Usage: @apiParam (MyGroup) {Number} id Users unique ID.
Examples:
/**
* @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.
*/
@apiParamExample
参数使用说明
@apiParamExample [{type}] [title]
example
Usage: @apiParamExample {json} Request-Example:
{ "content": "This is an example content" }
Example:
/**
* @api {get} /user/:id
* @apiParamExample {json} Request-Example:
* {
* "id": 4711
* }
*/
@apiPermission
权限
@apiPermission name
Usage: @apiPermission admin
Example:
/**
* @api {get} /user/:id
* @apiPermission none
*/
@apiSampleRequest
设置api的模拟请求接口，会生成form表单
@apiSampleRequest url
url可以是绝对，相对路径，相对路径会使用全局的sampleUrl设置来作为前缀,绝对路径会覆盖全局设置，也可以使用@apiSampleRequest off来关闭
url Url to your test api server.
Overwrite the configuration parameter sampleUrl and append @api url:
@apiSampleRequest http://www.example.com
Prefix the @api url:
@apiSampleRequest /my_test_path
Disable api test if configuration parameter sampleUrl is set:
@apiSampleRequest off
Usage: @apiSampleRequest http://test.github.com
Examples:
This will send the api request to http://api.github.com/user/:id
Configuration parameter sampleUrl: "http://api.github.com"
/**
* @api {get} /user/:id
*/
@apiSuccess
成功返回
@apiSuccess [(group)] [{type}] field [description]
Usage: @apiSuccess {String} firstname Firstname of the User.
Example:
/**
* @api {get} /user/:id
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*/
Example with (group), more group-examples at @apiSuccessTitle:
/**
* @api {get} /user/:id
* @apiSuccess (200) {String} firstname Firstname of the User.
* @apiSuccess (200) {String} lastname Lastname of the User.
*/
Example with Object:
/**
* @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.
*/
Example with Array:
/**
* @api {get} /users
* @apiSuccess {Object[]} profiles List of user profiles.
* @apiSuccess {Number} profiles.age Users age.
* @apiSuccess {String} profiles.image Avatar-Image.
*/
@apiSuccessExample
成功返回demo
@apiSuccessExample [{type}] [title]
example
Usage: @apiSuccessExample {json} Success-Response:
{ "content": "This is an example content" }
Example:
/**
* @api {get} /user/:id
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*/
@apiUse
使用经过@apiDefine已经定义的块
@apiUse name
Usage: @apiUse MySuccess
Example:
/**
* @apiDefine MySuccess
* @apiSuccess {string} firstname The users firstname.
* @apiSuccess {number} age The users age.
*/
/**
* @api {get} /user/:id
* @apiUse MySuccess
*/
@apiVersion
设置版本api信息
@apiVersion version
Usage: @apiVersion 1.6.2
Example:
/**
* @api {get} /user/:id
* @apiVersion 1.6.2
*/