摘要：個(gè)人博客同步文章是一款利用源代碼中注釋來(lái)創(chuàng)建文檔的工具。用法和類(lèi)似錯(cuò)誤返回消息的示例，作為預(yù)格式化代碼輸出。設(shè)置文檔塊的版本。如果您在源代碼中留下過(guò)時(shí)或未完成的方法并且您不希望將其發(fā)布到文檔中，那么它很有用。

個(gè)人博客同步文章 https://mr-houzi.com/2018/07/...

apidoc是一款利用源代碼中注釋來(lái)創(chuàng)建RESTful Web API文檔的工具。apidoc可用于C＃，Go，Dart，Java，JavaScript，PHP，TypeScript和所有其他支持Javadoc的語(yǔ)言。

npm install apidoc -g

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

myapp/ 根據(jù)myapp文件夾下文件的注釋進(jìn)行創(chuàng)建文檔

apidoc/ 文檔的輸出位置

mytemplate/ 使用的模板

查看幫助，用于顯示命令行參數(shù)：

apidoc -h

在apidoc.json配置項(xiàng)目的基本信息

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

apidoc也支持通過(guò)package.json進(jìn)行設(shè)置，只需在"apidoc":{}下添加參數(shù)即可。

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

如果你想設(shè)置header和footer，把下面信息加入到apidoc.json中（別忘記創(chuàng)建markdown文件）。

{
  "header": {
    "title": "My own header title",
    "filename": "header.md"
  },
  "footer": {
    "title": "My own footer title",
    "filename": "footer.md"
  }
}

接下來(lái)給大家介紹一下常用的參數(shù)，完整介紹大家可以自己看一下官方文檔，正常情況來(lái)說(shuō)下面這些就夠用。

@api {method} path [title]

聲明一下請(qǐng)求方法、請(qǐng)求路徑等。

eg:

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

@apiDeprecated [text]

將API方法標(biāo)記為已棄用

@apiDescription text

API方法的詳細(xì)描述。

@apiName name

定義方法文檔塊的名稱(chēng)。名稱(chēng)將用于生成的輸出中的子導(dǎo)航。結(jié)構(gòu)定義不需要@apiName。

eg:

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

@apiGroup name

定義方法文檔塊屬于哪個(gè)組。組將用于生成的輸出中的主導(dǎo)航。例如：login和register接口都可以劃分到User組。

eg:

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

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

描述API-Header傳遞的參數(shù)，例如用于授權(quán)。

eg:

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

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

用來(lái)描述API傳參值

eg:

 /** @apiParam (params) {int} time 時(shí)間戳(用于判斷請(qǐng)求是否超時(shí))
   * @apiParam (params) {String} token 確認(rèn)來(lái)訪者身份
   * @apiParam (params) {String} user_name 手機(jī)號(hào)或者郵箱
   * @apiParam (params) {String} user_pwd MD5加密的用戶(hù)密碼
   */

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

成功返回參數(shù)。用法和@apiParam類(lèi)似。個(gè)人認(rèn)為@apiSuccess有點(diǎn)多余，使用@apiSuccessExample就足夠了。

@apiSuccessExample [{type}] [title] example

成功返回消息的示例，作為預(yù)格式化代碼輸出。

eg:

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

錯(cuò)誤返回參數(shù)。用法和@apiSuccess類(lèi)似

錯(cuò)誤返回消息的示例，作為預(yù)格式化代碼輸出。用法和@apiSuccessExample類(lèi)似。

@apiVersion version

設(shè)置文檔塊的版本。版本也可用于@apiDefine。

eg:

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

@apiIgnore [hint]

將它放在一個(gè)塊的頂部。
@apiIgnore將無(wú)法解析塊。如果您在源代碼中留下過(guò)時(shí)或未完成的方法并且您不希望將其發(fā)布到文檔中，那么它很有用。

eg:

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

來(lái)一個(gè)完整的例子

/**
 * @api {post} /user/login 用戶(hù)登錄
 * @apiName login
 * @apiGroup User
 * @apiParam (params) {int} time 時(shí)間戳(用于判斷請(qǐng)求是否超時(shí))
 * @apiParam (params) {String} token 確認(rèn)來(lái)訪者身份
 * @apiParam (params) {String} user_name 手機(jī)號(hào)或者郵箱
 * @apiParam (params) {String} user_pwd MD5加密的用戶(hù)密碼
 * @apiSuccessExample Success-Response:
 *  {
 *      "code": 200,
 *      "msg": "登錄成功！",
 *      "data": {
 *           "uid": 1, //用戶(hù)ID
 *           "user_phone": "13011111111", //用戶(hù)手機(jī)號(hào)
 *           "user_nickname": "小明", //用戶(hù)昵稱(chēng)
 *           "user_email": "123456789@163.com", //用戶(hù)郵箱
 *           "user_rtime": 1501414343 //用戶(hù)注冊(cè)時(shí)間
 *  }
 *
 */

效果：