网站首页技术博客

apidoc自动化文档生成

洞天水月2021-05-10 09:16:36130人次阅读
摘要apiDOC 是一款通过注释或注解生成 API 文档的工具,支持 Java、PHP、JS 等多种语言,生成方便。 一、客户端工具的安装 apiDoc客户端工具基于nodejs开发,所以安装前需要先安装nodejs,node.js下载。 apidoc的安装 npm install apidoc -g 二、使用说明 在应用根目录创建apidoc.json { "name

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}}`意为数值介于100
999之间
{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,显示效果如下:

文章评论