网站首页技术博客
apidoc自动化文档生成
apiDOC 是一款通过注释或注解生成 API 文档的工具,支持 Java、PHP、JS 等多种语言,生成方便。
一、客户端工具的安装
apiDoc客户端工具基于nodejs开发,所以安装前需要先安装nodejs,node.js下载。
apidoc的安装
npm install apidoc -g
二、使用说明
在应用根目录创建apidoc.json
{
"name": "风伯云风物流管理系统",
"version": "0.1.0",
"description": "文档描述",
"title": "风伯云风物流管理系统",
"url" : "http://fbysdev.jrsmc.com"
}
写代码注释
一个完整的例子
class Test
{
/**
* @apiDefine userApiStr 用户接口文档
*/
/**
* @api {POST} /login 用户登录
* @apiName api测试
* @apiGroup userApiStr
* @apiVersion 1.0.0
* @apiDescription 用于用户登录
* @apiParam {String} userName 用户名
* @apiParam {String} password 密码
* @apiParamExample {json} 请求样例:
* ?userName=张三&password=11223344
* @apiSuccess (200) {String} msg 信息
* @apiSuccess (200) {String} code 0 代表无错误 1代表有错误
* @apiSuccess (200) {String} user 用户信息
* @apiSuccess (200) {String} userId 用户id
* @apiSuccessExample {json} 返回样例:
* {"code":"0","msg":"登录成功","userId":"fe6386d550bd434b8cd994b58c3f8075"}
*/
public function test()
{
}
}
三、apidoc注释参数
3.1 @api
【必填字段】否则,apidoc会忽略该条注释
@api {method} path [title]
参数列表:
参数 | 必填 | 描述 |
---|---|---|
method | yes | 请求类型:DELETE, GET, POST, PUT, ...更多 |
path | yes | 请求路径 |
title | no | 接口标题 |
例:
/**
* @api {get} /user/:id
*/
3.2 @apiDefine
@apiDefine name [title]
[description]
定义注释模块(类似于代码中定义一个常量),对于一些通用可复用的注释模块(例如:接口错误响应模块),只需要在源代码中定义一次,便可以在其他注释模块中随便引用,最后在文档导出时会自动替换所引用的注释模块,定义之后您可以通过@apiUse
来引入所定义的注释模块。(注:可以同时使用@apiVersion
来定义注释模块的版本)
参数列表:
参数 | 必填 | 描述 |
---|---|---|
name | yes | 注释模块名称(唯一),不同@apiVersion 可以定义相同名称的注释模块 |
title | no | 注释模块标题 |
description | no | 注释模块详细描述(详细描述另起一行,可包含多行) |
例:
/**
* @apiDefine MyError
* @apiError UserNotFound The id
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
*/
3.3 @apiDeprecated
@apiDeprecated [text]
标注一个接口已经被弃用
参数列表:
参数 | 必填 | 描述 |
---|---|---|
text | yes | 多行文字描述 |
例:
**
* @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
@apiDescription text
api接口的详细描述
参数列表:
参数 | 必填 | 描述 |
---|---|---|
text | yes | 多行文字描述 |
/**
* @apiDescription This is the Description.
* It is multiline capable.
*
* Last line of Description.
*/
3.5 @apiError
@apiError [(group)] [{type}] field [description]
错误返回参数
参数列表:
参数 | 必填 | 描述 |
---|---|---|
(group) | no | 所有的参数都会通过这个参数进行分组,如果未设置,默认值为Error 4xx |
{type} | no | 返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]} ) |
field | yes | 返回id |
description | no | 参数描述 |
例:
/**
* @api {get} /user/:id
* @apiError UserNotFound The id
of the User was not found.
*/
3.6 @apiErrorExample
@apiErrorExample [{type}] [title]
example
接口错误返回示例(格式化输出)
参数列表:
参数 | 必填 | 描述 |
---|---|---|
type | no | 响应类型 |
title | no | 示例标题 |
example | yes | 示例详情(兼容多行) |
例:
/**
* @api {get} /user/:id
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
3.7 @apiExample
@apiExample [{type}] title
example
接口方式请求示例
参数列表:
参数 | 必填 | 描述 |
---|---|---|
type | no | 请求内容格式 |
title | yes | 示例标题 |
example | yes | 示例详情(兼容多行) |
/**
* @api {get} /user/:id
* @apiExample {curl} Example usage:
* curl -i http://localhost/user/4711
*/
3.8 @apiGroup
@apiGroup name
定义接口所属的接口组,虽然接口定义里不需要这个参数,但是您应该在每个接口注释里都添加这个参数,因为导出的接口文档会以接口组的形式导航展示。
参数列表:
参数 | 必填 | 描述 |
---|---|---|
name | yes | 接口组名称(用于导航,不支持中文) |
例:
/**
* @api {get} /user/:id
* @apiGroup User
*/
3.9 @apiHeader
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
描述接口请求头部需要的参数(功能类似@apiParam
)
参数列表:
参数 | 必填 | 描述 |
---|---|---|
(group) | no | 所有的参数都会以该参数值进行分组(默认Parameter ) |
{type} | no | 返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]} ) |
field | yes | 参数名称(定义该头部参数为必填) |
[field] | yes | 参数名称(定义该头部参数为可选) |
=defaultValue | no | 参数默认值 |
description | no | 参数描述 |
例:
/**
* @api {get} /user/:id
* @apiHeader {String} access-key Users unique access-key.
*/
3.10 @apiHeaderExample
@apiHeaderExample [{type}] [title]
example
请求头部参数示例
参数列表:
参数 | 必填 | 描述 |
---|---|---|
type | no | 请求内容格式 |
title | no | 请求示例标题 |
example | yes | 请求示例详情(兼容多行) |
例:
/**
* @api {get} /user/:id
* @apiHeaderExample {json} Header-Example:
* {
* "Accept-Encoding": "Accept-Encoding: gzip, deflate"
* }
*/
3.11 @apiIgnore
@apiIgnore [hint]
如果你需要使用该参数,请把它放到注释块的最前面。如果设置了该参数,那么该注释模块将不会被解析(当有些接口还未完成或未投入使用时,可以使用该字段)
参数列表:
参数 | 必填 | 描述 |
---|---|---|
hint | no | 描接口忽略原因描述 |
例:
/**
* @apiIgnore Not finished Method
* @api {get} /user/:id
*/
3.12 @apiName
@apiName name
接口名称,每一个接口注释里都应该添加该字段,在导出的接口文档里会已该字段值作为导航子标题,如果两个接口的@apiVersion
和@apiName
一样,那么有一个接口的注释将会被覆盖(接口文档里不会展示)
参数列表:
参数 | 必填 | 描述 |
---|---|---|
name | yes | 接口名称(相同接口版本下所有接口名称应该是唯一的) |
例:
/**
* @api {get} /user/:id
* @apiName GetUser
*/
3.13 @apiParam
@apiParam [(group)] [{type}] [field=defaultValue] [description]
接口请求体参数
参数列表:
参数 | 必填 | 描述 |
---|---|---|
(group) | no | 所有的参数都会以该参数值进行分组(默认Parameter ) |
{type} | no | 返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]} ) |
{type{size}} | no | 返回类型,同时定义参数的范围{string{..5}} 意为字符串长度不超过5{string{2..5}} 意为字符串长度介于25之间`{number{100-999}}`意为数值介于100999之间 |
{type=allowedValues} | no | 参数可选值{string="small"} 意为字符串仅允许值为"small"{string="small","huge"} 意为字符串允许值为"small"、"huge"{number=1,2,3,99} 意为数值允许值为1、2、3、99{string {..5}="small","huge" 意为字符串最大长度为5并且值允许为:"small"、"huge" |
field | yes | 参数名称(定义该请求体参数为必填) |
[field] | yes | 参数名称(定义该请求体参数为可选) |
=defaultValue | no | 参数默认值 |
description | no | 参数描述 |
例:
/**
* @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.
*/
3.14 @apiParamExample
@apiParamExample [{type}] [title]
example
请求体参数示例
参数列表:
参数 | 必填 | 描述 |
---|---|---|
type | no | 请求内容格式 |
title | no | 请求示例标题 |
example | yes | 请求示例详情(兼容多行) |
例:
/**
* @api {get} /user/:id
* @apiParamExample {json} Request-Example:
* {
* "id": 4711
* }
*/
3.15 @apiPermission
允许访问该接口的角色名称
@apiPermission name
参数列表:
参数 | 必填 | 描述 |
---|---|---|
name | yes | 允许访问的角色名称(唯一) |
例:
/**
* @api {get} /user/:id
* @apiPermission none
*/
3.16 @apiPrivate
@apiPrivate
定义私有接口,对于定义为私有的接口,可以在生成接口文档的时候,通过在命令行中设置参数 --private false|true
来决定导出的文档中是否包含私有接口
例:
/**
* @api {get} /user/:id
* @apiPrivate
*/
3.17 @apiSampleRequest
@apiSampleRequest url
设置了该参数后,导出的html接口文档中会包含模拟接口请求的form表单;如果在配置文件apidoc.json
中设置了参数sampleUrl
,那么导出的文档中每一个接口都会包含模拟接口请求的form表单,如果既设置了sampleUrl
参数,同时也不希望当前这个接口不包含模拟接口请求的form表单,可以使用@apiSampleRequest off
来关闭。
参数列表:
参数 | 必填 | 描述 |
---|---|---|
url | yes | 模拟接口请求的url@apiSampleRequest http://www.example.com 意为覆盖apidoc.json 中的sampleUrl 参数@apiSampleRequest off 意为关闭接口测试功能 |
例:
发送测试请求到:http://api.github.com/user/:id
Configuration parameter sampleUrl: "http://api.github.com"
/**
* @api {get} /user/:id
*/
发送测试请求到:http://test.github.com/some_path/user/:id
(覆盖apidoc.json
中的sampleUrl
参数)
Configuration parameter sampleUrl: "http://api.github.com"
/**
* @api {get} /user/:id
* @apiSampleRequest http://test.github.com/some_path/
*/
关闭接口测试功能
Configuration parameter sampleUrl: "http://api.github.com"
/**
* @api {get} /user/:id
* @apiSampleRequest off
*/
发送测试请求到http://api.github.com/some_path/user/:id
(由于没有设置apidoc.json
中的sampleUrl
参数,所以只有当前接口有模拟测试功能)
Configuration parameter sampleUrl is not set
/**
* @api {get} /user/:id
* @apiSampleRequest http://api.github.com/some_path/
*/
3.18 @apiSuccess
@apiSuccess [(group)] [{type}] field [description]
接口成功返回参数
参数列表:
参数 | 必填 | 描述 |
---|---|---|
(group) | no | 所有的参数都会以该参数值进行分组,默认值:Success 200 |
{type} | no | 返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]} ) |
field | yes | 返回值(返回成功码) |
=defaultValue | no | 参数默认值 |
description | no | 参数描述 |
例:
/**
* @api {get} /user/:id
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*/
包含(group)
:
/**
* @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.
*/
3.19 @apiSuccessExample
@apiSuccessExample [{type}] [title]
example
返回成功示例
参数列表:
参数 | 必填 | 描述 |
---|---|---|
type | no | 返回内容格式 |
title | no | 返回示例标题 |
example | yes | 返回示例详情(兼容多行) |
例:
/**
* @api {get} /user/:id
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*/
3.20@apiUse
@apiUse name
引入注释模块,如果当前模块定义了@apiVersion
,那么版本相同或版本最近的注释模块会被引入
参数列表:
参数 | 必填 | 描述 |
---|---|---|
name | yes | 引入注释模块的名称 |
例:
/**
* @apiDefine MySuccess
* @apiSuccess {string} firstname The users firstname.
* @apiSuccess {number} age The users age.
*/
/**
* @api {get} /user/:id
* @apiUse MySuccess
*/
3.21 @apiVersion
@apiVersion version
定义接口/注释模块版本
参数列表:
参数 | 必填 | 描述 |
---|---|---|
version | yes | 版本号(支持APR版本规则:major.minor.patch) |
例:
/**
* @api {get} /user/:id
* @apiVersion 1.6.2
*/
四、如何生成
在含有配置文件的目录下,使用DOS命令:
apidoc -i 源代码目录 -o 输出文档目录
例子:
apidoc -i app/api/controller -o apidocs/
该命令将会读取所在目录下的所有注释,并生成文档页面到所在目录的apidocs目录下。
访问apidocs目录下的index.html,显示效果如下: