使用apidoc文檔神器，快速生成api文檔

寫完api接口，就須要編寫api文檔了，若是一個個手寫的話就很麻煩，就得使用apidoc只須要經過寫註釋，就能夠快速生成文檔了。

安裝

第一步先安裝全局模塊apidoc。

npm install apidoc -g

修改接口的註釋

找到novel-api項目routes下面的index.js文件，註釋修改爲以下

/**
 * @api {get} /index 請求首頁數據
 * @apiVersion 1.0.0
 * @apiName 獲取首頁數據
 * @apiGroup index
 *
 *
 * @apiSuccess {Number} flag 是否獲取到數據 1成功 0失敗
 * @apiSuccess {Array} books 返回書籍內容
 * @apiSuccess {String} msg  返回信息
 *
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *    {
 *      "flag": 1,
 *      "books": [
 *          {
 *             "_id": "5816b415b06d1d32157790b1",
 *            "title": "聖墟",
 *            "author": "辰東",
 *            "shortIntro": "在破敗中崛起，在寂滅中復甦。滄海成塵，雷電枯竭，那一縷幽霧又一次臨近大地，世間的枷鎖被打開了，一個全新的世界就此揭開神祕的一角……",
 *            "cover": "http://statics.zhuishushenqi.com/agent/http%3A%2F%2Fimg.1391.com%2Fapi%2Fv1%2Fbookcenter%2Fcover%2F1%2F1228859%2F1228859_fac7917a960547eb953edf0b740cef3a.jpg%2F",
 *            "site": "zhuishuvip",
 *            "majorCate": "玄幻",
 *            "minorCate": "東方玄幻",
 *            "allowMonthly": false,
 *            "banned": 0,
 *            "latelyFollower": 283375,
 *            "retentionRatio": "73.42"
 *          }
 *      ],
 *      "msg": "OK"
 *    }
 *
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     { "flag": 0, "msg": "rankingId有問題" }
 */

@api {method} path [title]
@api 若是沒有@api apidoc會忽略這段註釋
method 請求的方法
path 路徑
title 標題

@apiVersion version
設置文檔塊的版本。
version 版本號

@apiName name
定義方法文檔塊的名稱。名稱將用於生成的輸出中的子導航。
name 方法的名稱

@apiGroup name
定義方法文檔塊屬於哪一個組。組將用於生成的輸出中的主導航。
name 組的名稱。也用做導航標題。

@apiSuccess [(group)] [{type}] field [description]
成功返回參數。
(group) 可選 全部參數將按這個名稱分組。沒有組，默認Success 200設置。
{type} 可選 返回類型
field 返回標識符
description 描述

@apiParamExample [{type}] [title]

example

參數請求示例。
{type} 可選 響應格式
title 示例的簡稱
example 詳細的例子

@apiErrorExample [{type}] [title]

example

錯誤返回消息的示例，輸出爲預格式化代碼。
{type} 可選 響應格式
title 示例的簡稱
example 詳細的例子

配置npm run doc

打開package.json文件增長doc命令配置

"doc": "apidoc -i routes/ -o public/"

routes/ 要輸出API文檔的文件夾。
public/ 輸出文檔到public文件夾，沒有回自動建立。
執行 npm run doc
訪問 http://localhost:3000/ 就能夠看到生成好的API文檔了。

線上生成的文檔地址

https://api.langpz.com/

個人博客和github，喜歡就去點點星吧，謝謝。

https://github.com/lanpangzhi

http://blog.langpz.com

參考

https://github.com/apidoc/apidoc