本文基于
node.js的代碼注釋編寫。
程序員都不喜歡寫文檔，但是程序員習慣寫注釋。所以今天給大家安利一個注釋文檔的工具——apidoc，一個在注釋里邊編寫API文檔的小工具！
由于經驗以及英文水平問題，文中很有可能會有錯漏，各位大神如果看出來了，麻煩指出一下。謝謝～
安裝apidoc
npm install -g apidoc
運行
apidoc -i myapp/ -o apidoc/ -t mytemplate/
- -i 需要編譯的包含注釋的文件
- -o 輸入文件夾名稱
- t 模板
具體的詳細幫助可以通過apidoc -h查看。
設置（apidoc.json）
我們可以通過apidoc.json文件來設置項目API文檔的一些內容。例如：
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}
又或者通過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"
}
}
簡單介紹一下注釋的編寫
因為apidoc官網已經有詳細的介紹了，所以這里就只是簡單的介紹寫apidoc常用的語法。
@api
@api一般是必須編寫的（除非你是用了@apiDefine），不然apidoc編譯器會忽略這段注釋。
/**
* @api {method} path [title]
*/
| Name | Description |
|---|---|
| method | 請求的方法名稱：如GET、POST等等 |
| path | 請求路徑 |
| title(可選) | 一個簡短的標題（用于導航跟文檔標題） |
@apiGroup
定于api歸屬的組名，生成的文檔會把該api注釋歸類到該值對應的api組上。
/**
* @apiGroup name
*/
| Name | Description |
|---|---|
| name | 組名稱 |
@apiName
@apiName用于定義API文檔的一個實例，并用作實例名稱 。
/**
* @apiName name
*/
| Name | Description |
|---|---|
| name | 實例名稱 |
@apiParam
@apiParam用于編寫API的參數以及參數的解釋。
/**
* @apiParam [(group)] [{type}] [field=defaultValue] [description]
*/
| Name | Description |
|---|---|
(group) 可選
|
參數歸屬組名，不填寫組名，則默認設為Paramter
|
{type} 可選
|
參數數據類型，如{String}、{Number}、{Array}等等 |
{type{size}} 可選
|
變量的大小信息 {String{..5}}參數類型為一個字符不超過5的字符串；{String{2..5}}參數為一個字符在2到5之間的字符串； |
{type=allowedValues} 可選
|
參數允許值 {string="small","huge"}參數只能接受small或者huge的字符串 |
field 可選
|
參數名稱 |
| =defaultValue | 參數默認值 |
| description(可選) | 描述 |
@apiParamExample
@apiParamExample參數例子
/**
* @apiParamExample [{type}] [title]
* example
*/
| Name | Description |
|---|---|
{type} 可選
|
請求數據結構 |
title 可選
|
例子的一個簡短的標題 |
| example | 例子的詳細信息，可多個例子并存 |
@apiSuccess
請求成功后的返回字段參數
/**
* @apiSuccess [(group)] [{type}] field [description]
*/
| Name | Description |
|---|---|
(group) 可選
|
參數歸屬組名，不填寫組名，則默認設為Success 200
|
{type} 可選
|
返回的數據類型，如{String}、{Number}等等 |
| field | 返回的標示符（返回成功的狀態碼） |
description 可選
|
描述 |
@apiSuccessExample
請求成功后返回的字段參數例子
/**
* @apiSuccessExample [{type}] [title] example
*/
| Name | Description |
|---|---|
{type} 可選
|
請求數據結構 |
title 可選
|
例子的一個簡短的標題 |
| example | 例子的詳細信息，可多個例子并存 |
@apiError & @apiErrorExample
這個的用法跟@apiSuccess、@apiSuccessExample的用法相類似。
舉個栗子
下邊舉一個根據id獲取文章資源API的例子
/**
* @api {get} /articles/:id 根據單個id獲取文章信息
* @apiName 根據id獲取文章信息
* @apiGroup Articles
*
* @apiParam (params) {String} id 文章id
*
* @apiSuccess {Array} article 返回相應id的文章信息
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "tile": "文章標題2",
* "date": 1483941498230,
* "author": "classlfz",
* "content": "文章的詳細內容"
* }
*
* @apiError (Error 4xx) 404 對應id的文章信息不存在
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 對應id的文章信息不存在
* {
* "error": err
* }
*/
接著我們運行apidoc -i src/ -o docs，就會看到項目里邊多了一個docs的文件夾，打開里邊的index.html，就可以看到生成的API文檔了。如下圖：
這樣子，我們就可以輕松的通過注釋得到一個API文檔了，而不需要在寫完代碼之后還要去打開word或者md文件去另外編寫API文檔......對于我本人而言，我是比較喜歡這樣子的工作方式的。
如果項目是放在github上邊的話，我們可以使用github pages來公布API文檔，方便協同開發。
寫成gulp任務
因為平時用gulp比較多，這里再補上通過gulp任務來生成apidoc文檔。
安裝依賴
npm install gulp gulp-apidoc --save-dev
編寫gulp代碼
// 構建apidoc
gulp.task('apidoc', (done) => {
apidoc({
src: 'src/',
dest: 'docs',
debug: true,
includeFilters: ['.*\\.js$']
}, done);
});
