linux 使用apidoc 生成Restful web Api文档

朱雀 2022-03-06 18:16 307阅读 0赞

官方文档：[http://apidocjs.com/\#example-basic][http_apidocjs.com_example-basic]

博客：[https://blog.csdn.net/soslinken/article/details/50468896][https_blog.csdn.net_soslinken_article_details_50468896]

在项目开发过程中，总会牵扯到接口文档的设计与编写，之前使用的都是[office][]工具，写一个文档，总也是不够漂亮和直观。好在git上的开源大神提供了生成文档的工具，so来介绍一下！  
该工具是Nodejs的模块，请务必在使用前安装好nodejs环境！

工具名称：apiDoc  
Git地址：https://github.com/apidoc/apidoc  
项目地址：http://apidocjs.com/  
样例项目：http://apidocjs.com/example\_basic/  
apoDoc是从源码的注释中生成RestFul api 文档，样子还是蛮漂亮的……

## 一、apidoc简介 ##

apidoc是一款可以有源代码中的注释直接自动生成api接口文档的工具，它几乎支持目前主流的所有风格的注释。例如：  
Javadoc风格注释(可以在C\#, Go, Dart, Java, JavaScript, PHP, TypeScript等语言中使用)

/**
     * This is a comment.
     */

CoffeeScript

###
    This is a comment.
    ###

Elixir

@apidoc """
    This is a comment.
    """

Erlang (注释中的‘%’是可选的)

%{
    % This is a comment.
    %}

Perl (Doxygen)

#**
    # This is a comment.
    #*

Python

"""
    This is a comment.
    """

Ruby

=begin
    This is a comment.
    =end

Lua

--[[
    This is a comment.
    --]]

## 二、apidoc使用 ##

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

npm install apidoc -g

运行：

apidoc -i myapp/ -o apidoc/ -t mytemplate/

### 2.1 apidoc 命令参数列表： ###

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

### 2.2 配置(apidoc.json) ###

每次导出接口文档都必须要让apidoc读取到`apidoc.json`文件(如果未添加配置文件，导出报错)，你可以在你项目的根目录下添加`apidoc.json`文件，这个文件主要包含一些项目的描述信息，比如标题、简短的描述、版本等，你也可以加入一些可选的配置项，比如页眉、页脚、模板等。  
**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`文件(例如:node.js工程)，那么你可以将`apidoc.json`文件中的所有配置信息放到`package.json`文件中的*apidoc*参数中：  
**package.json**

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

**apidoc.json配置项**

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

## 三、 apidoc注释参数 ##

### 3.1 @api ###

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

@api {method} path [title]

参数列表:

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>必填</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>method</td> 
   <td>yes</td> 
   <td>请求类型:DELETE, GET, POST, PUT, ...<a href="https://link.jianshu.com?t=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FHypertext_Transfer_Protocol%23Request_methods" rel="nofollow">更多</a></td> 
  </tr> 
  <tr> 
   <td>path</td> 
   <td>yes</td> 
   <td>请求路径</td> 
  </tr> 
  <tr> 
   <td>title</td> 
   <td>no</td> 
   <td>接口标题</td> 
  </tr> 
 </tbody> 
</table>

例：

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

### 3.2 @apiDefine ###

@apiDefine name [title]
                         [description]

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

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>必填</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>name</td> 
   <td>yes</td> 
   <td>注释模块名称(唯一)，不同<code>@apiVersion</code>可以定义相同名称的注释模块</td> 
  </tr> 
  <tr> 
   <td>title</td> 
   <td>no</td> 
   <td>注释模块标题</td> 
  </tr> 
  <tr> 
   <td>description</td> 
   <td>no</td> 
   <td>注释模块详细描述(详细描述另起一行，可包含多行)</td> 
  </tr> 
 </tbody> 
</table>

例:

/**
     * @apiDefine MyError
     * @apiError UserNotFound The <code>id</code> of the User was not found.
     */
    
    /**
     * @api {get} /user/:id
     * @apiUse MyError
     */

/**
     * @apiDefine admin User access only
     * This optional description belong to to the group admin.
     */
    
    /**
     * @api {get} /user/:id
     * @apiPermission admin
     */

### 3.3 @apiDeprecated ###

@apiDeprecated [text]

标注一个接口已经被弃用  
参数列表:

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>必填</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>text</td> 
   <td>yes</td> 
   <td>多行文字描述</td> 
  </tr> 
 </tbody> 
</table>

例：

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

### 3.4 @apiDescription ###

@apiDescription text

api接口的详细描述  
参数列表:

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

### 3.5 @apiError ###

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

错误返回参数  
参数列表:

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>必填</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>(group)</td> 
   <td>no</td> 
   <td>所有的参数都会通过这个参数进行分组，如果未设置，默认值为<code>Error 4xx</code></td> 
  </tr> 
  <tr> 
   <td>{type}</td> 
   <td>no</td> 
   <td>返回类型(例如:<code>{Boolean}, {Number}, {String}, {Object}, {String[]}</code>)</td> 
  </tr> 
  <tr> 
   <td>field</td> 
   <td>yes</td> 
   <td>返回id</td> 
  </tr> 
  <tr> 
   <td>description</td> 
   <td>no</td> 
   <td>参数描述</td> 
  </tr> 
 </tbody> 
</table>

例:

/**
     * @api {get} /user/:id
     * @apiError UserNotFound The <code>id</code> of the User was not found.
     */

### 3.6 @apiErrorExample ###

@apiErrorExample [{type}] [title]
                     example

接口错误返回示例(格式化输出)  
参数列表:

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>必填</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>type</td> 
   <td>no</td> 
   <td>响应类型</td> 
  </tr> 
  <tr> 
   <td>title</td> 
   <td>no</td> 
   <td>示例标题</td> 
  </tr> 
  <tr> 
   <td>example</td> 
   <td>yes</td> 
   <td>示例详情(兼容多行)</td> 
  </tr> 
 </tbody> 
</table>

例:

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

### 3.7 @apiExample ###

@apiExample [{type}] title
                example

接口方式请求示例  
参数列表:

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>必填</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>type</td> 
   <td>no</td> 
   <td>请求内容格式</td> 
  </tr> 
  <tr> 
   <td>title</td> 
   <td>yes</td> 
   <td>示例标题</td> 
  </tr> 
  <tr> 
   <td>example</td> 
   <td>yes</td> 
   <td>示例详情(兼容多行)</td> 
  </tr> 
 </tbody> 
</table>

/**
     * @api {get} /user/:id
     * @apiExample {curl} Example usage:
     *     curl -i http://localhost/user/4711
     */

### 3.8 @apiGroup ###

@apiGroup name

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

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>必填</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>name</td> 
   <td>yes</td> 
   <td>接口组名称(用于导航,不支持中文)</td> 
  </tr> 
 </tbody> 
</table>

例：

/**
     * @api {get} /user/:id
     * @apiGroup User
     */

### 3.9 @apiHeader ###

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

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

例:

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

### 3.10 @apiHeaderExample ###

@apiHeaderExample [{type}] [title]
                       example

请求头部参数示例  
参数列表:

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>必填</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>type</td> 
   <td>no</td> 
   <td>请求内容格式</td> 
  </tr> 
  <tr> 
   <td>title</td> 
   <td>no</td> 
   <td>请求示例标题</td> 
  </tr> 
  <tr> 
   <td>example</td> 
   <td>yes</td> 
   <td>请求示例详情(兼容多行)</td> 
  </tr> 
 </tbody> 
</table>

例：

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

### 3.11 @apiIgnore ###

@apiIgnore [hint]

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

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>必填</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>hint</td> 
   <td>no</td> 
   <td>描接口忽略原因描述</td> 
  </tr> 
 </tbody> 
</table>

例：

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

### 3.12 @apiName ###

@apiName name

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

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>必填</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>name</td> 
   <td>yes</td> 
   <td>接口名称(相同接口版本下所有接口名称应该是唯一的)</td> 
  </tr> 
 </tbody> 
</table>

例：

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

### 3.13 @apiParam ###

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

接口请求体参数  
参数列表:

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>必填</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>(group)</td> 
   <td>no</td> 
   <td>所有的参数都会以该参数值进行分组(默认<code>Parameter</code>)</td> 
  </tr> 
  <tr> 
   <td>{type}</td> 
   <td>no</td> 
   <td>返回类型(例如:<code>{Boolean}, {Number}, {String}, {Object}, {String[]}</code>)</td> 
  </tr> 
  <tr> 
   <td>{type{size}}</td> 
   <td>no</td> 
   <td>返回类型,同时定义参数的范围<br><code>{string{..5}}</code>意为字符串长度不超过5<br><code>{string{2..5}}</code>意为字符串长度介于25之间&lt;br/&gt;`{number{100-999}}`意为数值介于100999之间</td> 
  </tr> 
  <tr> 
   <td>{type=allowedValues}</td> 
   <td>no</td> 
   <td>参数可选值<br><code>{string="small"}</code>意为字符串仅允许值为"small"<br><code>{string="small","huge"}</code>意为字符串允许值为"small"、"huge"<br><code>{number=1,2,3,99}</code>意为数值允许值为1、2、3、99<br><code>{string {..5}="small","huge"</code>意为字符串最大长度为5并且值允许为:"small"、"huge"</td> 
  </tr> 
  <tr> 
   <td>field</td> 
   <td>yes</td> 
   <td>参数名称(定义该请求体参数为必填)</td> 
  </tr> 
  <tr> 
   <td>[field]</td> 
   <td>yes</td> 
   <td>参数名称(定义该请求体参数为可选)</td> 
  </tr> 
  <tr> 
   <td>=defaultValue</td> 
   <td>no</td> 
   <td>参数默认值</td> 
  </tr> 
  <tr> 
   <td>description</td> 
   <td>no</td> 
   <td>参数描述</td> 
  </tr> 
 </tbody> 
</table>

例:

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

### 3.14 @apiParamExample ###

@apiParamExample [{type}] [title]
                       example

请求体参数示例  
参数列表:

例：

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

### 3.15 @apiPermission ###

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

@apiPermission name

参数列表:

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>必填</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>name</td> 
   <td>yes</td> 
   <td>允许访问的角色名称(唯一)</td> 
  </tr> 
 </tbody> 
</table>

例：

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

### 3.16 @apiPrivate ###

@apiPrivate

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

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

### 3.17 @apiSampleRequest ###

@apiSampleRequest url

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

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>必填</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>url</td> 
   <td>yes</td> 
   <td>模拟接口请求的url<br><code>@apiSampleRequest http://www.example.com</code>意为覆盖<code>apidoc.json</code>中的<code>sampleUrl</code>参数<br><code>@apiSampleRequest off</code>意为关闭接口测试功能</td> 
  </tr> 
 </tbody> 
</table>

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

Configuration parameter sampleUrl: "http://api.github.com"
    /**
     * @api {get} /user/:id
     */

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

Configuration parameter sampleUrl: "http://api.github.com"
    /**
     * @api {get} /user/:id
     * @apiSampleRequest http://test.github.com/some_path/
     */

关闭接口测试功能

Configuration parameter sampleUrl: "http://api.github.com"
    /**
     * @api {get} /user/:id
     * @apiSampleRequest off
     */

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

Configuration parameter sampleUrl is not set
    /**
     * @api {get} /user/:id
     * @apiSampleRequest http://api.github.com/some_path/
     */

### 3.18 @apiSuccess ###

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

接口成功返回参数  
参数列表:

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>必填</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>(group)</td> 
   <td>no</td> 
   <td>所有的参数都会以该参数值进行分组,默认值:<code>Success 200</code></td> 
  </tr> 
  <tr> 
   <td>{type}</td> 
   <td>no</td> 
   <td>返回类型(例如:<code>{Boolean}, {Number}, {String}, {Object}, {String[]}</code>)</td> 
  </tr> 
  <tr> 
   <td>field</td> 
   <td>yes</td> 
   <td>返回值(返回成功码)</td> 
  </tr> 
  <tr> 
   <td>=defaultValue</td> 
   <td>no</td> 
   <td>参数默认值</td> 
  </tr> 
  <tr> 
   <td>description</td> 
   <td>no</td> 
   <td>参数描述</td> 
  </tr> 
 </tbody> 
</table>

例:

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

包含`(group)`:

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

返回参数中有对象:

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

### 3.19 @apiSuccessExample ###

@apiSuccessExample [{type}] [title]
                       example

返回成功示例  
参数列表:

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>必填</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>type</td> 
   <td>no</td> 
   <td>返回内容格式</td> 
  </tr> 
  <tr> 
   <td>title</td> 
   <td>no</td> 
   <td>返回示例标题</td> 
  </tr> 
  <tr> 
   <td>example</td> 
   <td>yes</td> 
   <td>返回示例详情(兼容多行)</td> 
  </tr> 
 </tbody> 
</table>

例：

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

### 3.20@apiUse ###

@apiUse name

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

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>必填</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>name</td> 
   <td>yes</td> 
   <td>引入注释模块的名称</td> 
  </tr> 
 </tbody> 
</table>

例:

/**
     * @apiDefine MySuccess
     * @apiSuccess {string} firstname The users firstname.
     * @apiSuccess {number} age The users age.
     */
    
    /**
     * @api {get} /user/:id
     * @apiUse MySuccess
     */

### 3.21 @apiVersion ###

@apiVersion version

定义接口/注释模块版本  
参数列表:

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>必填</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>version</td> 
   <td>yes</td> 
   <td>版本号(支持APR版本规则:major.minor.patch)</td> 
  </tr> 
 </tbody> 
</table>

例:

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

注：文中如有任何错误，请各位批评指正！

链接：https://www.jianshu.com/p/9353d5cc1ef8

实践：

node安装：[https://blog.csdn.net/mengzuchao/article/details/88761308][https_blog.csdn.net_mengzuchao_article_details_88761308]