node后台 apidoc快速生成你的api文档

昨天发现了一个好东西 apidoc，真的很方便。支持当下很多编程语言

安利一波node项目下快速上手

安装

npm install apidoc -g

配置

我以express 写的接口为例

// 方便大家入门，我把注释写在后面，但是实际情况最好去掉，毕竟是根据它编译生成api文档的
//  后面是注释


/**
 * @api {get} /book/bookCategory/cateList 书籍分类列表查找   规定请求类型 接口地址 api标题 接口地址想显示全的话，后续说到配置文件 apidoc.json 中 url 统一在前面添加
 * @apiName 书籍分类列表查找    api标题 跟上面保持一致
 * @apiGroup Book   分组 比如书籍好几个接口，我就用Book作为分组的栏目
 *
 * @apiParam {String} parentId 父级分类id，默认0（顶级分类）   传递的参数 类型 和 说明
 * 
 * @apiSampleRequest /book/bookCategory/cateList    模拟请求
 * 
 * @apiSuccess {Number} status 状态码.   请求成功后返回的字段 类型
 * @apiSuccess {String} title 标题.
 * @apiSuccess {String} description 描述.
 */

router.get('/bookCategory/cateList', (req, res) => {
  const parentId = req.query.parentId || 0
  bookCateModel.find({parentId})
    .then(category => {
      res.send({status: 0, data: category})
    })
    .catch(error => {
      res.send({status: 1, message: '获取分类信息异常, 请重新尝试'})
    })
})

根目录下添加整个文件的配置文件apidoc.json,基本配置

{
  "name": "我的接口文档",
  "version": "0.0.2",
  "description": "书籍类型接口文档",
  "title": "书籍接口文档",
  "url" : "https://www.xxxx:3333/api",
  "sampleUrl": "https://www.xxxx:3333/api"  模拟接口请求前缀,统一写
}

生成文档

导出文件是一个静态文件，直接打开都可以用的。我为了方便，放在public。

apidoc -i 你的文件位置 -o 导出文件位置 [-t 模板文件]   你的文件位置可以是文件夹

apidoc -i routes -o public/apidoc  默认模板还好，所以我没配, 如果你编译出来很多{ message: xxx ,warning } 命令行加 [ -e node_modules ] 忽略依赖项文件

当然还有一些配置，感兴趣的话，可以去官网看哦。如果对你有所帮助，记得点个赞呗。