当前位置: 首页 > 工具软件 > APIdoc-Go > 使用案例 >

apiDoc之api接口文档生成

皮骏
2023-12-01

 

  • 安装apidoc
  • 配置(apidoc.json)
    • apidoc.json配置项
  • apidoc注释参数
    • @api
    • @apiErrorExample
    • @apiDefine
    • @apiDeprecated
    • @apiDescription
    • @apiError
    • @apiExample
    • @apiGroup
    • @apiParam
    • @apiHeader
    • @apiHeaderExample
    • @apiIgnore
    • @apiName
    • @apiParamExample
    • @apiPermission
    • @apiPrivate
    • @apiSampleRequest
    • @apiSuccess
    • @apiSuccessExample
    • @apiUse
    • @apiVersion
  • 生成接口文档

 

安装apidoc

官网

通过npm安装,请提前安装好npm

可以通过以下命令安装apidoc:

npm install apidoc -g

配置(apidoc.json)

每次导出接口文档都必须要让apidoc读取到apidoc.json文件(如果未添加配置文件,导出报错),你可以在你项目的根目录下添加apidoc.json文件,这个文件主要包含一些项目的描述信息,比如标题、简短的描述、版本等,你也可以加入一些可选的配置项,比如页眉、页脚、模板等。
apidoc.json

{
  "name": "系统接口文档",
  "version": "0.0.1",
  "description": "文档总描述",
  "title": "apidoc浏览器自定义标题",
  "url" : "文档url地址"
}

如果你的项目中使用了package.json文件(例如:node.js工程),那么你可以将apidoc.json文件中的所有配置信息放到package.json文件中的apidoc参数中:
package.json

{
 "name": "系统接口文档",
  "version": "0.0.1",
  "description": "文档总描述",
  "apidoc": {
    "title": "apidoc浏览器自定义标题",
 	 "url" : "文档url地址"
  }
}

apidoc.json配置项

参数描述
name工程名称如果apidoc.json文件中没有配置该参数,apidoc会尝试从pakcage.json文件中读取
version版本如果apidoc.json文件中没有配置该参数,apidoc会尝试从pakcage.json文件中读取
description工程描述如果apidoc.json文件中没有配置该参数,apidoc会尝试从pakcage.json文件中读取
title浏览器标题
urlapi路径前缀例如:https://api.github.com/v1
sampleUrl如果设置了该参数,那么在文档中便可以看到用于测试接口的一个表单(详情可以查看参数@apiSampleReques)
header.title页眉导航标题
header.filename页眉文件名(markdown)
footer.title页脚导航标题
footer.filename页脚文件名(markdown)
order接口名称或接口组名称的排序列表如果未定义,那么所有名称会自动排序"order": [ "Error", "Define", "PostTitleAndError", PostError"]

更多详情

apidoc注释参数

@api

【必填字段】否则,apidoc会忽略该条注释

@api {method} path [title]

参数列表:

参数必填描述
methodyes请求类型:DELETE, GET, POST, PUT, ...更多
pathyes请求路径
titleno接口标题

例:

/**
* @api {get} /user/getUserById/:id 获取用户数据 - 根据id
*/

@apiErrorExample

接口错误返回示例(格式化输出)

@apiErrorExample [{type}] [title]
                 example

参数列表:

参数必填描述
typeno响应类型
titleno示例标题
exampleyes示例详情(兼容多行)

例:

/**
 *@api {get} /user/getUserById/:id 获取用户数据 - 根据id
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

@apiDefine

定义注释模块(类似于代码中定义一个常量),对于一些通用可复用的注释模块(例如:接口错误响应模块),只需要在源代码中定义一次,便可以在其他注释模块中随便引用,最后在文档导出时会自动替换所引用的注释模块,定义之后您可以通过@apiUse来引入所定义的注释模块。(注:可以同时使用@apiVersion来定义注释模块的版本)

@apiDefine name [title] [description]

参数列表:

参数必填描述
nameyes注释模块名称(唯一),不同@apiVersion可以定义相同名称的注释模块
titleno注释模块标题
descriptionno注释模块详细描述(详细描述另起一行,可包含多行)

例:

/**
 * @apiDefine        FailResponse
 * @apiErrorExample  Response (fail):
 *     {
 *       "code":"error"
 *       "error_message": "错误内容"
 *     }
 */

/**
 * @apiDefine        SuccessResponse
 * @apiSuccessExample  Response (success):
 *     {
 *       "code":"0"
 *       "error_message": ""
 *       "data":"内容"
 *     }
 */

/**
 * @apiUse             SuccessResponse
 *
 * @apiUse             FailResponse
 */

@apiDeprecated

标注一个接口已经被弃用

@apiDeprecated [text]

参数列表:

参数必填描述
textyes多行文字描述

例:

/**
 * @apiDeprecated use now (#Group:Name).
 *
 * Example: to set a link to the GetDetails method of your group User
 * write (#User:GetDetails)
 */

@apiDescription

api接口的详细描述

@apiDescription [text]

参数列表:

参数必填描述
textyes多行文字描述

例:

/**
 * @apiDescription This is the Description.
 * It is multiline capable.
 *
 * Last line of Description.
 */

@apiError

错误返回参数

@apiError [(group)] [{type}] field [description]

参数列表:

参数必填描述
(group)no所有的参数都会通过这个参数进行分组,如果未设置,默认值为Error 4xx
{type}no返回类型,例如{Boolean}{Number}{String}{Object}{String[]}(字符串数组),…
fieldyes返回id
descriptionno参数描述

例:

/**
 * @api {get} /user/getUserById/:id 获取用户数据 - 根据id
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 */
 
/**
 * @apiError (错误分组) {Object} xxx xxxxxxxx
 */

@apiExample

接口方式请求示例

@apiExample [{type}] title
            example

参数列表:

参数必填描述
typeno请求内容格式
titleyes示例标题
exampleyes示例详情(兼容多行)

例:

/**
 * @api {get} /user/getUserById/:id
 * @apiExample {curl} Example usage:
 *     curl -i http://127.0.0.1/user/getUserById/1
 */

@apiGroup

定义接口所属的接口组,虽然接口定义里不需要这个参数,但是您应该在每个接口注释里都添加这个参数,因为导出的接口文档会以接口组的形式导航展示。

@apiGroup name

参数列表:

参数必填描述
nameyes接口组名称(用于导航,不支持中文)

例:

/**
 * @apiDefine User 用户信息
 */
/**
 * @api {get} /user/getUserById/:id
 * @apiGroup User
 */

@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”
fieldyes参数名称(定义该请求体参数为必填)
[field]yes参数名称(定义该请求体参数为可选)
=defaultValueno参数默认值
descriptionno参数描述

例:

/**
 * @api {get} /user/getUserById/: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.
 */

@apiHeader

描述接口请求头部需要的参数(功能类似@apiParam)

@apiHeader [(group)] [{type}] [field=defaultValue] [description]

参数列表:

参数必填描述
(group)no所有的参数都会以该参数值进行分组(默认Parameter)
{type}no返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
fieldyes参数名称(定义该头部参数为必填)
[field]yes参数名称(定义该头部参数为可选)
=defaultValueno参数默认值
descriptionno参数描述

例:

/**
 * @api {get} /user/getUserById/:id
 * @apiHeader {String} access-key Users unique access-key.
 */

@apiHeaderExample

请求头部参数示例

@apiHeaderExample [{type}] [title]
                   example

参数列表:

参数必填描述
typeno请求内容格式
titleno请求示例标题
exampleyes请求示例详情(兼容多行)

例:

/**
 * @api {get} /user/getUserById/:id
 * @apiHeaderExample {json} Header-Example:
 *     {
 *       "Accept-Encoding": "Accept-Encoding: gzip, deflate"
 *     }
 */

@apiIgnore

如果你需要使用该参数,请把它放到注释块的最前面。如果设置了该参数,那么该注释模块将不会被解析(当有些接口还未完成或未投入使用时,可以使用该字段)

@apiIgnore [hint]

参数列表:

参数必填描述
hintno描接口忽略原因描述

例:

/**
 * @apiIgnore Not finished Method
 * @api {get} /user/getUserById/:id
 */

@apiName

接口名称,每一个接口注释里都应该添加该字段,在导出的接口文档里会已该字段值作为导航子标题,如果两个接口的@apiVersion和@apiName一样,那么有一个接口的注释将会被覆盖(接口文档里不会展示)

@apiName name

参数列表:

参数必填描述
nameyes接口名称(相同接口版本下所有接口名称应该是唯一的)

例:

/**
 * @api {get} /user/getUserById/:id
 * @apiName getUserById
 */

@apiParamExample

请求体参数示例

@apiParamExample [{type}] [title]
                   example

参数列表:

参数必填描述
typeno请求内容格式
titleno请求示例标题
exampleyes请求示例详情(兼容多行)

例:

/**
 * @api {get} /user/getUserById/:id
 * @apiParamExample {json} Request-Example:
 *     {
 *       "id": 1
 *     }
 */

@apiPermission

允许访问该接口的角色名称

@apiPermission name

参数列表:

参数必填描述
nameyes允许访问的角色名称(唯一)

例:

/**
 * @api {get} /user/getUserById/:id
 * @apiPermission none
 */

@apiPrivate

定义私有接口,对于定义为私有的接口,可以在生成接口文档的时候,通过在命令行中设置参数 --private false|true来决定导出的文档中是否包含私有接口

@apiPrivate

例:

/**
 * @api {get} /user/getUserById/:id
 * @apiPrivate
 */

@apiSampleRequest

设置了该参数后,导出的html接口文档中会包含模拟接口请求的form表单;如果在配置文件apidoc.json中设置了参数sampleUrl,那么导出的文档中每一个接口都会包含模拟接口请求的form表单,如果既设置了sampleUrl参数,同时也不希望当前这个接口不包含模拟接口请求的form表单,可以使用@apiSampleRequest off来关闭。

@apiSampleRequest url

参数列表:

参数必填描述
urlyes模拟接口请求的url@apiSampleRequest http://www.example.com意为覆盖apidoc.json中的sampleUrl参数@apiSampleRequest off意为关闭接口测试功能

例:
发送测试请求到:http://api.github.com/user/getUserById/:id

/**
 * @api {get} /user/getUserById/:id
 */

发送测试请求到:http://test.github.com/some_path/user/getUserById/:id(覆盖apidoc.json中的sampleUrl参数)

/**
 * @api {get} /user/getUserById/:id
 * @apiSampleRequest http://test.github.com/some_path/
 */

关闭接口测试功能

/**
 * @api {get} /user/getUserById/:id
 * @apiSampleRequest off
 */

发送测试请求到http://api.github.com/some_path/user/getUserById/:id(由于没有设置apidoc.json中的sampleUrl参数,所以只有当前接口有模拟测试功能)

/**
 * @api {get} /user/getUserById/:id
 * @apiSampleRequest http://api.github.com/some_path/
 */

@apiSuccess

接口成功返回参数

@apiSuccess [(group)] [{type}] field [description]

参数列表:

参数必填描述
(group)no所有的参数都会以该参数值进行分组,默认值:Success 200
{type}no返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
fieldyes返回值(返回成功码)
=defaultValueno参数默认值
descriptionno参数描述

例:

/**
 * @api {get} /user/getUserById/:id
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

包含(group):

/**
 * @api {get} /user/getUserById/:id
 * @apiSuccess (200) {String} firstname Firstname of the User.
 * @apiSuccess (200) {String} lastname  Lastname of the User.
 */

返回参数中有对象:

/**
 * @api {get} /user/getUserById/: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.
 */

@apiSuccessExample

返回成功示例

@apiSuccessExample [{type}] [title]
                   example

参数列表:

参数必填描述
typeno返回内容格式
titleno返回示例标题
exampleyes返回示例详情(兼容多行)

例:

/**
 * @api {get} /user/getUserById/:id
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "code":"0"
 *       "message": ""
 *       "data":"加密内容"
 *     }
 */

@apiUse

引入注释模块,如果当前模块定义了@apiVersion,那么版本相同或版本最近的注释模块会被引入

@apiUse name

参数列表:

参数必填描述
nameyes引入注释模块的名称

例:

/**
 * @apiDefine MySuccess
 * @apiSuccess {string} firstname The users firstname.
 * @apiSuccess {number} age The users age.
 */

/**
 * @api {get} /user/getUserById/:id
 * @apiUse MySuccess
 */

@apiVersion

定义接口/注释模块版本

@apiVersion version

参数列表:

参数必填描述
versionyes版本号(支持APR版本规则:major.minor.patch)

例:

/**
 * @api {get} /user/getUserById/:id
 * @apiVersion 1.6.2
 */

小诀窍,笔者把接口中的通用部分利用apiDefine摘出来,放在一个公共文件中,之后可以利用apiUse去调用,或许部分注释参数可以直接使用apiDefine即可调用。

生成接口文档

当然你注释参数写好了之后它也不会帮你自动生成,你需要自己运行以下命令:
例:

apidoc -f ".*\\.php$"  -i ./application -o ./public/apidoc

参数列表:

参数描述
-h, --help查看帮助文档
-f --file-filters指定读取文件的文件名过滤正则表达式(可指定多个)例如: apidoc -f “.*\.js&quot;−f&quot;.∗.ts
"−f".∗.ts” 意为只读取后缀名为js和ts的文件默认值:.clj .cls .coffee .cpp .cs .dart .erl .exs? .go .groovy .ino? .java .js .jsx .kt .litcoffee lua .p .php? .pl .pm .py .rb .scala .ts .vue
-e --exclude-filters指定不读取的文件名过滤正则表达式(可指定多个)例如:apidoc -e “.*\.js$” 意为不读取后缀名为js的文件默认:’’
-i, --input指定读取源文件的目录例如:apidoc -i myapp/ 意为读取myapp/目录下面的源文件默认值:./
-o, --output指定输出文档的目录例如:apidoc -o doc/ 意为输出文档到doc目录下默认值:./doc/
-t, --template指定输出的模板文件例如:apidoc -t mytemplate/默认:path.join(__dirname, ‘…/template/’)(使用默认模板)
-c, --config指定包含配置文件(apidoc.json)的目录例如:apidoc -c config/默认:./
-p, --private输出的文档中是否包含私有api例如:apidoc -p true 默认:false
-v, --verbose是否输出详细的debug信息例如:apidoc -v true默认:false

之后你就能通过浏览器进行访问了,比如http://localhost/apidoc

 类似资料: