[apidoc]Apidoc-文档生成工具

大家好，欢迎来到IT知识分享网。

Apidoc主要是用于生成API文档的工具，可以用于多种语言，包括java、javascript、php等

这里主要是为了写前端的APIDOC，方便交互是双方的使用;

工具的安装

工具包的安装

npm i apidoc [-g|-D] 

可以-g全局安装，或者-D局部安装,因为只有开发环境需要apidoc包，因此项目依赖只需要放置在devDependencies中即可

VSCODE编辑器的支持，可以在扩展中搜索ApiDoc,最上面的ApiDoc Snippets是最受欢迎的支持工具，可以点击安装

APIDOC的生成

apidoc的配置文件

关于Apidoc的配置有两种方式，一种是在项目根目录中添加apidoc.json，另一种是直接在package.json种添加apidoc的配置

1. 添加 apidoc.json 方式

{ "name": "example", "version": "0.1.0", "description": "apiDoc basic example", "title": "Custom apiDoc browser title", "url" : "https://api.github.com/v1" } 

2. 在package.json中添加配置方式

{ "name": "example", "version": "0.1.0", "description": "apiDoc basic example", "apidoc": { "title": "Custom apiDoc browser title", "url" : "apiDoc base interface url" } } 

注意：

使用第二种方式时，因为 package.json 本身包含name，version，description等属性，若是apidoc不设置该属性，将使用package.json设置的属性值

若是第一种方式，不包含这些属性，可能使用apidoc包的默认值

apidoc配置属性

完整配置

{ "name": "ApiDoc 服务", "title": "ApiDoc 服务", "version": "0.1.0", "description": "Mock服务API文档", "url": "http://127.0.0.1", "sampleUrl": true, "header": { "title": "ApiDOC介绍", "filename": "apidoc.md" }, "footer": { "title": "综合介绍", "filename": "apidoc.md" }, "order":[] } 

当输入参数后点击发送按钮后显示Response，示例如下:

Apidoc文档生成

全局安装的apidoc,可以在项目的根目录下打开cmd终端，并执行以下命令；

如果是项目安装的apidoc，可以将以下命令添加到package.json文件的scripts中，可以直接双击执行该命令，避免每次接口变化时都要重新输入该命令,生成接口文档

apidoc -i 编译文件夹 -o 输出文件夹 

编译文件夹 ：就是需要输出接口文档的文件所在文件夹，apidoc文档会自动识别相关参数，并编译这些代码文件

输出文件夹:生成接口文档的存储文件夹

apidoc命令执行后，根据命令生成的静态html页面，可以在输出文件夹点击html页面查看生成的静态页面，页面即是接口的列表

Api支持的标签

以下是关于标签的详细使用说明

@api

定义接口

@api {method} path title 

• method:get、post、put等定义接口交互类型
• path：定义接口路径，如果路径中存在参数，使用:attr表明是路径参数
• title：接口名称或描述

示例

@api {post} /user/del 删除设置 @api {get} /user/:nav 导航设置 

@apiDescription

api的详细描述，text可以多行

@apiDescription text 

@apiGroup

用于对@api接口分组,不用于@apiDefine，最好使用英文，否则编译后分组会出现错误

@apiGroup name 

@apiName

用于导航的html源代码节点属性data-name等，不能在UI页面上直观的看到展示,不用于@apiDefine；因为是添加到html的属性上，所以推荐英文,主要是用作锚点，用于href等属性

@apiName name 

@apiDeprecated

标记api废弃

@apiDeprecated [text] 

@apiDeprecated [废弃描述] 

如果当前接口被废弃，有了可替换的新的接口，可以在描述中添加新接口的锚点链接，方便用户查看

//定义的接口 @apiGroup groupName @apiName apiName //废弃接口 @apiDeprecated [废弃描述] [#groupName:apiName] 

点击锚点跳转到分组groupName下的，名字为apiName的接口，因为涉及锚点跳转因此推荐这两个属性都使用英文命名

@apiIgnore

@apiIgnore [hint] 

接口编译时忽略，apidoc中根本不显示该接口，没有该接口的任何信息，而@apiDeprecated则是在接口名称下添加Deprecated红色标记

@apiPrivate

给接口设置私有标签，然后根据生成文档的命令决定是否生成带有私有标签的接口

@apiPrivate 

生成显示私有标签的接口：

apidoc -i ./bin -o ./apidoc --private 

不生成显示私有标签的接口：

apidoc -i ./bin -o ./apidoc 

@apiVersion

设置接口文档的版本

@apiVersion version 

@apiSampleRequest

用于单独设置某个接口是否显示请求示例pannel。

若sampleUrl已经设置，就近原则，覆盖全局设置的apidoc.json文档中的设置 sampleUrl；

@apiSampleRequest url 

• url ： http接口前缀，或者路径前缀，例如：http://apidoc.com, /prefix/path

关闭当前接口的请求示例pannel：

@apiSampleRequest off 

@apiPermission

导出一个权限的名称，如果该名称被@apiDefine 添加了注释，则鼠标滑过会有说明

@apiPermission name 

@apiDefine

可以单独定义一个通用的结构，方便被其它多个@api的定义引用

@apiDefine name [title] [description] 

• name ： 定义块的名称
• title ： 如果name值是 @apiPermission 或者 @apiParam的名称时，该值就是弹框的别名
• description ： 当title是@apiPermission的值时才显示

普通的使用

定义结构：

/ * @apiDefine ResSuccess * @apiSuccess {string} resCode response code. * @apiSuccess {string} resMes response Message. * @apiSuccess {json} [data] response data. */ 

此时结构中，如果定义description，此内容不会被引入

使用结构：

/ * @api {post} /user/del 删除设置 * @apiUse ResSuccess */ 

作为 apiPermission 的说明

定义结构：

/ * @apiDefine permission Manager * Manager user access * @apiSuccess {string} resCode response code. */ 

此时结构中，如果定义其它内容，例如@apiSuccess不会被引入@api,只是作为@apiPermission的一个注释

使用结构：

/ * @api {post} /user/del 删除设置 * @apiPermission permission */ 

当定义了一个符合apiPermission标准的结构时，并定义了@apiSuccess等内容时，如果使用@apiUse引入，则引入成功返回的参数pannel，如果使用@apiPermission引入，则引入定义的说明文字与别名

@apiUse

用于使用@apiDefine定义的结构

@apiUse name 

• name，@apiDefine结构名称

@apiQuery

定义传递给接口的参数,查询参数,给apidoc添加Query Parameter(s)的pannel

@apiQuery [{type}] [field=defaultValue] [description] 

• type ： 定义参数类型，{string}，{boolean}等
  • {type{size}}：

    {string{…5}} 限定string长度最多5个字符.

    {string{2…5}} 限定string长度2-5个字符

    {number{100-999}} 限定参数属于 100 到 999之间

  • {type=allowedValues}

    {string=“small”} 只有一个可选值

    {string=“small”,“huge”} 有多个可选值

    {number=1,2,3,99} 有多个可选值

    {string {…5}=“small”,“huge”} type设置size 与 allowedValues混合写法

• field ： 属性名称
  • [field] 当前参数可选，非必选参数
  • field[nestedField] 内嵌属性

    @apiParam {Object} [address] 可选address参数 @apiParam {String} [address[street]] 可选内嵌street参数 

  • =defaultValue 设置默认值
• description ： 参数描述信息
  
  

@apiBody

定义传递给接口的参数,给apidoc添加Request Body的pannel

@apiBody [{type}] [field=defaultValue] [description] 

@apiParam

该标签用于定义api参数,为apidoc添加参数pannel，并且推荐定义出现在@api path中的参数，否则会报警

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

• group ： 定义pannel的名字，默认Parameter
• type ： 定义参数类型，{string}，{boolean}等
  • {type{size}}：

    {string{…5}} 限定string长度最多5个字符.

    {string{2…5}} 限定string长度2-5个字符

    {number{100-999}} 限定参数属于 100 到 999之间

  • {type=allowedValues}

    {string=“small”} 只有一个可选值

    {string=“small”,“huge”} 有多个可选值

    {number=1,2,3,99} 有多个可选值

    {string {…5}=“small”,“huge”} type设置size 与 allowedValues混合写法

• field ： 属性名称
  • [field] 当前参数可选，非必选参数
  • field[nestedField] 内嵌属性

    @apiParam {Object} [address] 可选address参数 @apiParam {String} [address[street]] 可选内嵌street参数 

  • =defaultValue 设置默认值
• description ： 参数描述信息
  
  

@apiParamExample

该标签用于定义api参数多行示例,为apidoc添加示例块

@apiParamExample [{type}] [title] example 

注意，example 另起一行，就按照上述格式

• type ： 参数数据类型
• title ： 参数名称
• example ： 是一个块状示例描述，多行

@apiExample

api的使用示例,为apidoc添加示例块

@apiExample [{type}] title example 

• type ： 代码语言
• title ： 示例的名称
• example ： 示例详情，多行

 @apiExample {curl} Example usage: curl -i http://localhost/user/4711 

@apiError

用于定义返回参数错误码，为接口添加返回错误码pannel

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

• group ： 定义参数错误码pannel名称
• type ： 定义参数类型，{string}，{boolean}等
• field：定义返回码
• description:描述

示例如下：

/ * @apiError UserNotFound The <code>id</code> of the User was not found. */ 

@apiErrorExample

用于定义返回参数错误码多行格式，例如Json格式的参数，为apidoc添加示例块

@apiErrorExample [{type}] [title] example 

• type ： 定义错误响应参数类型，一般是{json}
• title: 返回example的名称
• example: 是一个块状示例描述，多行

/ * @apiErrorExample {json} Error-Response: * HTTP/1.1 404 Not Found * { * "error": "UserNotFound" * } */ 

@apiHeader

描述传递给Api-Header的参数，为apidoc添加pannel

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

• group ： 定义参数分组名称，如果没有该值默认为Parameter
• type ： 定义参数类型，{string}，{boolean}等
• field ： 属性名称
  • [field] 当前参数可选，非必选参数
  • =defaultValue 设置默认值
• description ： 属性字段参数描述信息

标签示例：

@apiHeader (MyHeaderGroup) {String} authorization Authorization value 

@apiHeaderExample

描述传递给Api-Header的多行示例，为apidoc添加示例块

@apiHeaderExample [{type}] [title] example 

• type ： 请求格式
• title ： 示例example名称
• example ： 详情示例，多行示例

/* * @apiHeaderExample {json} Header-Example: * { * "Accept-Encoding": "AcceptEncoding: gzip, deflate" * } */ 

@apiSuccess

定义成功返回参数的Pannel，apidoc添加成功返回参数pannel

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

• group ： 定义成功返回pannel的名称，如果没设置，默认Success 200
• type ： 定义参数类型，{string}，{boolean}等
• field ： 定义返回属性，成功返回码
• description ： 属性字段参数描述信息

/ * @apiSuccess {Object[]} profiles List of user profiles. * @apiSuccess {Number} profiles.age Users age. * @apiSuccess {String} profiles.image Avatar-Image. */ 

@apiSuccessExample

定义成功返回多行参数的示例，例如Json格式的参数，为apidoc添加示例块

@apiSuccessExample [{type}] [title] example 

• type ： 定义成功返回示例类型
• title ： 示例example名称
• example ： 详情示例，多行示例，例如json

/* * @apiSuccessExample {json} Success-Response: * HTTP/1.1 200 OK * { * "firstname": "John", * "lastname": "Doe" * } */