共计 1788 个字符，预计需要花费 5 分钟才能阅读完成。
写完 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
