apidoc利用程式碼註釋書寫文件

weixin_33807284發表於2018-07-08
API
個人部落格同步文章 https://mr-houzi.com/2018/07/...
apidoc是一款利用原始碼中註釋來建立RESTful Web API文件的工具。apidoc可用於C＃，Go，Dart，Java，JavaScript，PHP，TypeScript和所有其他支援Javadoc的語言。

安裝

npm install apidoc -g

執行

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

myapp/ 根據myapp資料夾下檔案的註釋進行建立文件

apidoc/ 文件的輸出位置

mytemplate/ 使用的模板

命令列介面

檢視幫助，用於顯示命令列引數：

apidoc -h

配置（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"
}

apidoc也支援通過package.json進行設定，只需在"apidoc":{}下新增引數即可。

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

如果你想設定header和footer，把下面資訊加入到apidoc.json中（別忘記建立markdown檔案）。

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

使用

接下來給大家介紹一下常用的引數，完整介紹大家可以自己看一下官方文件，正常情況來說下面這些就夠用。

@api

@api {method} path [title]

宣告一下請求方法、請求路徑等。

名稱 描述
method 請求方法：DELETE，GET，POST，PUT，...
path 請求路徑
title 一個簡短的標題。（用於導航和文章標題）

eg:

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

@apiDeprecated

@apiDeprecated [text]

將API方法標記為已棄用

名稱 描述
text 文字描述

apiDescription

@apiDescription text

API方法的詳細描述。

名稱 描述
text 文字描述

@apiName

@apiName name

定義方法文件塊的名稱。名稱將用於生成的輸出中的子導航。結構定義不需要@apiName。

名稱 描述
name 方法的唯一名稱。 <br/> 格式：方法 + 路徑（例如Get + User），建議以這種方式命名

eg:

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

@apiGroup

@apiGroup name

定義方法文件塊屬於哪個組。組將用於生成的輸出中的主導航。例如：login和register介面都可以劃分到User組。

名稱 描述
name 組的名稱。也用作導航標題。

eg:

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

@apiHeader

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

描述API-Header傳遞的引數，例如用於授權。

名稱 描述
group 引數組別
type 引數型別
field 引數名
description 描述

eg:

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

@apiParam

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

用來描述API傳參值

名稱 描述
group 引數組別
type 引數型別
field 引數名
description 描述

eg:

 /** @apiParam (params) {int} time 時間戳(用於判斷請求是否超時)
   * @apiParam (params) {String} token 確認來訪者身份
   * @apiParam (params) {String} user_name 手機號或者郵箱
   * @apiParam (params) {String} user_pwd MD5加密的使用者密碼
   */

@apiSuccess

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

成功返回引數。用法和@apiParam類似。個人認為@apiSuccess有點多餘，使用@apiSuccessExample就足夠了。

@apiSuccessExample

@apiSuccessExample [{type}] [title] example

成功返回訊息的示例，作為預格式化程式碼輸出。

eg:

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

@apiError

錯誤返回引數。用法和@apiSuccess類似

@apiErrorExample

錯誤返回訊息的示例，作為預格式化程式碼輸出。用法和@apiSuccessExample類似。

@apiVersion

@apiVersion version

設定文件塊的版本。版本也可用於@apiDefine。

eg:

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

@apiIgnore

@apiIgnore [hint]

將它放在一個塊的頂部。
@apiIgnore將無法解析塊。如果您在原始碼中留下過時或未完成的方法並且您不希望將其釋出到文件中，那麼它很有用。

名稱 描述
hint 用於提示為什麼忽略這個塊。

eg:

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

舉個栗子

來一個完整的例子

/**
 * @api {post} /user/login 使用者登入
 * @apiName login
 * @apiGroup User
 * @apiParam (params) {int} time 時間戳(用於判斷請求是否超時)
 * @apiParam (params) {String} token 確認來訪者身份
 * @apiParam (params) {String} user_name 手機號或者郵箱
 * @apiParam (params) {String} user_pwd MD5加密的使用者密碼
 * @apiSuccessExample Success-Response:
 *  {
 *      "code": 200,
 *      "msg": "登入成功！",
 *      "data": {
 *           'uid': 1, //使用者ID
 *           'user_phone': '13011111111', //使用者手機號
 *           'user_nickname': '小明', //使用者暱稱
 *           'user_email': '123456789@163.com', //使用者郵箱
 *           'user_rtime': 1501414343 //使用者註冊時間
 *  }
 *
 */

效果：

相關文章