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的配置

添加 apidoc.json 方式

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

在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首页.
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

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

[apidoc]Apidoc-文档生成工具

工具的安装

APIDOC的生成

apidoc的配置文件

apidoc配置属性

Apidoc文档生成

Api支持的标签

@api

@apiDescription

@apiGroup

@apiName

@apiDeprecated

@apiIgnore

@apiPrivate

@apiVersion

@apiSampleRequest

@apiPermission

@apiDefine

@apiUse

@apiQuery

@apiBody

@apiParam

@apiParamExample

@apiExample

@apiError

@apiErrorExample

@apiHeader

@apiHeaderExample

@apiSuccess

@apiSuccessExample

相关文章