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":[]
}

设置header/footer，示例如下：

发送示例请求的pannel，示例如下：

当输入参数后点击发送按钮后显示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]

参数说明同 @apiQuery

@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"
*     }
*/