apiDoc从代码docblock生成api文档

官网手册：

第1章 前言

1.1 注释风格

使用Javadoc-Style（可用于C＃，Go，Dart，Java，JavaScript，PHP，TypeScript和所有其他具有Javadoc功能的语言）：

/**

* 这里全是注释。。。。。

*/

 

下面是个更多内容的注释

/**

 * @api {get} /user/:id 用户信息

 * @apiName GetUser

 * @apiGroup User

 *

 * @apiParam {Number} id Users unique ID.

 *

 * @apiSuccess {String} firstname Firstname of the User.

 * @apiSuccess {String} lastname  Lastname of the User.

 */

 

另外还支持以下语言（代码注释不同于Javadoc-Style）CoffeeScript、Elixir、Erlang、Perl、Python、Ruby、Lua

第2章 安装

2.1 npm安装

apt-get install nodejs

apt-get install npm

 

npm config set registry

 

npm install apidoc -g

或

cnpm install apidoc -g

2.2 运行

使用命令：

apidoc -i myapp/ -o apidoc/  [ -t mytemplate/ ]  [ -f ".*\.php$" ]

 

执行结果：

info: Done.

info: Nothing to do.

 

2.3 配置ApiDoc.json

name	Description
name	API的项目名，不设置将由apidoc自动生成
version	项目的版本号
description	项目的描述
title	浏览器的title
url	docBlock中@api的path前缀
sampleUrl	如果设置该值，将在所有的接口中生成一个测试表单，可以配合docBlock中@apiSampleRequest标签使用
header	title	被引入文件（header.md）的导航标题
	filename	被引入文件（header.md）的文件名markdown-file
footer	title	被引入文件（footer.md）的导航标题
	filename	被引入文件（footer.md）的文件名markdown-file
order	api的name列表或者group列表，对输出进行排序，未列出的部分顺序自动决定

 

2.4 apiDoc-Params

Param	Description	Option
@api	定义api的请求方法和路径	必选
@apiDefine	定义嵌入到@api块内的docBlock	可选
@apiDeprecated	将API标记为不推荐使用	可选
@apiDescription	API方法的详细描述。	可选
@apiError	错误返回的参数定义	可选
@apiErrorExample	错误返回的消息示例，预格式化代码输出。	可选
@apiExample	调用API的示例。作为预格式化代码输出。	可选
@apiGroup	定义docBlock所属的组	常用
@apiHeader	描述API header头参数，例如授权信息。	可选
@apiHeaderExample	API请求头的参数示例	可选
@apiIgnore	（放在docBlock顶部）该标签定义的docBlock不被解析，例如接口未完成时不想发布	可选
@apiName	定义docBlock的名字，用于子导航	常用
@apiParam	描述接口参数	可选
@apiParamExample	请求参数示例	可选
@apiPermission	接口的访问权限定义	可选
@apiPrivate	将API定义为私有，以允许创建两个API规范文档	可选
@apiSampleRequest	生成一个测试用的form表单，如果该参数为路径时可以与apidoc.json中的sampleUrl配合使用	可选
@apiSuccess	成功返回时的参数描述	可选
@apiSuccessExample	成功返回消息的示例，作为预格式化代码输出。	可选
@apiUse	引用@apiDefine定义的docBlock	可选
@apiVersion	docBlock的版本号	可选

 

 

第3章 Params使用

3.1  @api △

必选！！！

不给该参数，docBlock将被apiDoc解析器忽略。

但由@apiDefine定义的docBlock例外，不是必需的。

用法：@api {method} path [title]

示例：

/**

 * @api {get} /user/:id 获取用户信息

 */

这里如果不给title导航中会没有的，还是给出吧

3.2  @apiDefine √

定义被@api块引入的docBlock，每个docBlock只能引入一次，通过使用@apiUse导入，title和description可能被一起引入。

用法：@apiDefine name [title]

                     [description]

示例：

/**

 * @apiDefine MyError

 * @apiError UserNotFound The id of the User was not found.

 */

 

/**

 * @api {get} /user/:id

 * @apiUse MyError

 */

3.3  @apiDeprecated

将API标记为不推荐使用

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

提示：可以描述文本可以多行

示例：

/**

 * @apiDeprecated

 */

 

/**

 * @apiDeprecated use now (#Group:Name).

 *

 * Example: to set a link to the GetDetails method of your group User

 * write (#User:GetDetails)

 */

 

3.4  @apiDescription △

API的详细描述，可以多行

用法：@apiDescription This is the Description.

示例：

/**

 * @apiDescription This is the Description.

 * It is multiline capable.

 *

 * Last line of Description.

 */

 

3.5  @apiError √

错误返回的参数。

Usage: @apiError UserNotFound

示例：

/**

 * @api {get} /user/:id

 * @apiError UserNotFound The id of the User was not found.

 */

 

3.6  @apiErrorExample √

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

用法： @apiErrorExample {json} Error-Response:

                 This is an example.

示例：

/**

 * @api {get} /user/:id

 * @apiErrorExample {json} Error-Response:

 *     HTTP/1.1 404 Not Found

 *     {

 *       "error": "UserNotFound"

 *     }

 */

 

3.7  @apiExample

调用API的示例。预格式化代码输出。

用法： @apiExample {js} Example usage:

            This is an example.

示例：

/**

 * @api {get} /user/:id

 * @apiExample {curl} 调用示例:

 *     curl -i

 */

 

3.8  @apiGroup △

很常用！！！

定义API所属的组。组将用于文档主导航。

用法： @apiGroup User

例：

/**

 * @api {get} /user/:id

 * @apiGroup User

 */

 

3.9  @apiHeader

对API header头参数的描述，例如授权参数信息

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

例子：

/**

 * @api {get} /user/:id

 * @apiHeader {String} access-key Users unique access-key.

 */

 

3.10  @apiHeaderExample

API header参数请求示例。

用法： @apiHeaderExample {json} Request-Example:

                 { "content": "This is an example content" }

 

例：

/**

 * @api {get} /user/:id

 * @apiHeaderExample {json} Header-Example:

 *     {

 *       "Accept-Encoding": "Accept-Encoding: gzip, deflate"

 *     }

 */

 

3.11  @apiIgnore

将其放在docBlock的顶部。

@apiIgnore定义的docBlock不会被解析，未完成不想发布的接口用它

用法： @apiIgnore Not finished Method

例：

/**

 * @apiIgnore Not finished Method

 * @api {get} /user/:id

 */

 

3.12  @apiName △

很常用！！！

定义docBlock的名字，用于子导航

用法： @apiName GetUser

例：

/**

 * @api {get} /user/:id

 * @apiName GetUser

 */

 

3.13  @apiParam △

描述API调用时的参数

用法： @apiParam (MyGroup) {Number} id 用户唯一id.

 

例子：

/**

 * @api {get} /user/:id

 * @apiParam {Number} id Users unique ID.

 */

 

3.14  @apiParamExample

请求API的参数示例。

用法： @apiParamExample {json} Request-Example:

                 { "content": "This is an example content" }

例：

/**

 * @api {get} /user/:id

 * @apiParamExample {json} Request-Example:

 *     {

 *       "id": 4711

 *     }

 */

 

3.15  @apiPermission

输出API访问需要的权限名称

用法： @apiPermission admin

例：

/**

 * @api {get} /user/:id

 * @apiPermission none

 */

 

3.16  @apiPrivate

将API定义为私有，以允许创建两套API规范文档：排除私有API和包含私有API

用法： @apiPrivate

排除/包含私有API的命令行用法： --private false|true

例：

/**

 * @api {get} /user/:id

 * @apiPrivate

 */

 

3.17 @apiSampleRequest

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

如果sampleUrl设置，所有方法将具有api测试表单。

没有sampleUrl只有方法@apiSampleRequest，会有一个表单。

如果设置@apiSampleRequest url，则此url将用于测试表单的请求（当以http开头时，该url将覆盖sampleUrl）。

如果sampleUrl设置了，并且您不想使用测试表单的方法，则添加@apiSampleRequest off到文档块。

用法： @apiSampleRequest

例子：

/**

 * @api {get} /user/:id

 * @apiSampleRequest

 */

 

3.18 @apiSuccess △

成功返回参数。

用法： @apiSuccess {String} firstname Firstname of the User.

例：

/**

 * @api {get} /user/:id

 * @apiSuccess {String} firstname Firstname of the User.

 * @apiSuccess {String} lastname  Lastname of the User.

 */

 

3.19 @apiSuccessExample △

成功返回消息的示例，作为预格式化代码输出。

用法： @apiSuccessExample {json} Success-Response:

                   { "content": "This is an example content" }

例：

/**

 * @api {get} /user/:id

 * @apiSuccessExample {json} Success-Response:

 *     HTTP/1.1 200 OK

 *     {

 *       "firstname": "John",

 *       "lastname": "Doe"

 *     }

 */

 

3.20 @apiUse √

包含一个@apiDefine定义的docBlock

用法： @apiUse MySuccess

例：

/**

 * @apiDefine MySuccess

 * @apiSuccess {string} firstname The users firstname.

 * @apiSuccess {number} age The users age.

 */

 

/**

 * @api {get} /user/:id

 * @apiUse MySuccess

 */

 

3.21 @apiVersion △

设置docBlock的版本。也可以用在@apiDefine的docBlock。

具有相同group和name的docBlock，但version不同，生成的文档可以对比差异

用法： @apiVersion 1.6.2

例：

/**

 * @api {get} /user/:id

 * @apiVersion 1.6.2

 */