接口文檔利器apidoc

顧名思義，apidoc是用於接口文檔，並且是根據代碼註釋自動生成的，也能在線調用，類比swagger。  

apidoc官網。本文大部份內容摘自：ApiDoc 後端接口註釋文檔的使用

安裝

# 全局安裝
yarn global add apidoc 
# 查看是否安裝成功
apidoc -h 複製代碼

命令說明

• -f：--file-filters 過濾器，指定應該解析的文件類型、後綴 （能夠使用多個-f）。默認.cs .dart .erl .go .java .js .php .py .rb .ts。示例（僅解析.js和.ts文件）：apidoc -f ".*\.js" -f ".*\\.ts"
• -e：--exclude-filters 過濾器用於選擇不該該解析的文件
• -i： --input 指定輸入的源目錄名，項目文件的位置，默認爲 ./ 例：apidoc -i myapp/ 
• -o： --output 指定輸出的目錄文件名，放置生成文檔的位置，默認爲 ./doc/，例：apidoc -o apidoc/ 
• -t： --template 指定要用的外部模板的路徑，能夠建立和使用本身的模板，默認使用全局的 node_modules/apidoc/template/ ，例：apidoc -t mytemplate/ 
• -c： --config 指定配置文件的路徑 apidoc.json ./ 
• -h： --help 顯示詳細的幫助說明 
• --debug： --debug 顯示調試的信息，默認爲 false

使用說明

在項目文件夾下新建 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" : "https://api.github.com/v1"
  }
}複製代碼

詳細配置說明：

• name：項目名稱，若不存在該字段，則會嘗試取 package.json 裏面的name值 
• version：項目版本號，不存在則讀取 package.json 裏面對於的值 
• description：項目描述 ，不存在同上 
• title：瀏覽器標題文本 
• url：api路徑的前綴，適合同一域下的接口，例：https://api.github.com/v1 
• sampleUrl：測試樣例的url, 具體請參考 @apiSampleRequest 
• header：添加自定義的頂部描述 {title: '', filename: ''} 
• title：頂部的標題 
• filename：頂部具體的展示內容 
• footer：添加自定義的尾部描述 {title: '', filename: ''} 
• title：尾部的標題 
• filename：尾部具體的展示內容 
• order：用於定義輸出的api-names/group-name列表排序。最後自動顯示未定義的名稱。"order": ["Error","Define","PostTitleAndError","PostError"]
  

API說明

• 經常使用API：api、apiName、apiGroup、apiVersion、apiDescription、apiParam、apiSuccess、apiSuccessExample、apiDefine、apiError、apiIgnore，示例：

/**
 * @api {get} /user/:id Request User information
 * @apiVersion 0.1.0
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */複製代碼

文檔塊以 /** 和 */ 結尾，其中@api爲必須字段，格式同例子：@api + {請求類型} + 接口路徑 + 接口描述，在生成的時候沒有@api 的文檔塊會被忽略。@apiName 和 @apiGroup,在版本迭代時應保持一致，其餘字段爲可選。

• @api (必須字段，沒有會被忽略)

@api {method} path [title]複製代碼

示例：@api {get} /user/:id Users unique ID.

• @apiParam

@apiParam [(group)] [{type}] [field=defaultValue] [description]複製代碼

說明：1. 帶中括號[]的Fieldname將Variable定義爲可選，[]內部是須要的格式。2. =defaultValue 參數默認值。3.入參能夠用[(group)]進行分組。

示例：（2個）

/**
* @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.
*/複製代碼

• @apiSuccess

@apiSuccess [(group)] [{type}] field [description]複製代碼

示例：（3個）

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

/** * @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. */複製代碼

踩坑記錄

• 配置好、添加Demo註釋以後執行 apidoc 提示大量下面的錯誤。緣由是未屏蔽 node_modules ，須要添加-e，如apidoc -e node_modules，或者添加-i，如 apidoc -i src/。

{"message":"parser plugin 'return' not found in block: 13","level":"warn"}
{"message":"parser plugin 'param' not found in block: 14","level":"warn"}
{"message":"parser plugin 'return' not found in block: 14","level":"warn"}複製代碼

使用經驗

• 在node項目裏配置static文件訪問，以支持線上訪問接口文檔。