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 本身包含nameversiondescription等属性若是apidoc不设置该属性将使用package.json设置的属性值

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

apidoc配置属性

属性	描述
name	一般是项目名称显示在生成的apidoc首页.
version	项目的版本号 .
description	项目的描述信息.
title	是配置生成html的title标签
url	设置api接口的前缀所有api接口路径前会自动添加该值
sampleUrl	是否展示发送示例请求的pannel。取值URL,示例的接口请求前缀为该值取值true接口请求前缀为url属性值取值false或者属性不存在则不展示请求示例的操作pannel.@apiSampleRequest可以用来覆盖该值设置某个特别接口的特性.
header	apidoc导航的顶部目录可用于配置展示的md文件
title	顶部导航目录的名称
filename	顶部导航对应的引入的.md文件路径
footer	apidoc导航的底部目录可用于配置展示的md文件
title	底部导航目录的名称
filename	底部导航对应的引入的.md文件路径
order	可以用于定义 api-names / group-names 的导出目录顺序.若不设置该值顺序随机.“order”: [ “Error”, “Define”,“PostTitleAndError”, “PostError”]

完整配置

{
    "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 {method} path title	用于定义接口
@apiVersion version	设置接口文档的版本
@apiGroup name	接口分组
@apiDefine	定义结构块
@apiUse	使用定义的定义的@apiDefine结构
@apiPermission name	定义权限的名称
@apiDescription text	api的详细描述text可以多行
@apiName name	用于导航的html属性值主要是用作锚点
@apiPrivate	标记接口私有根据生成的命令是否存在–private决定是否生成该接口
@apiDeprecated [text]	标记api废弃
@apiIgnore [hint]	接口编译时忽略apidoc中不显示该接口
@apiSampleRequest	单独设置指定接口的请求pannel的显示
@apiQuery name	定义查询参数
@apiBody	定义接口的请求体
@apiExample	api使用示例
@apiParam	用于定义传递给@api的参数
@apiParamExample	用于定义@api中多行格式例如Json格式的参数
@apiError	用于定义错误码返回参数
@apiErrorExample	错误码返回参数多行格式例如Json格式的参数
@apiHeader	传递给api header的参数描述
@apiHeaderExample	传递给api header的多行参数描述
@apiSuccess	定义成功返回参数
@apiSuccessExample	定义成功返回多行参数例如Json格式的参数

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

@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

定义成功返回参数的Pannelapidoc添加成功返回参数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"
*     }
*/