APIDOC- API文档生成工具——node

后端的代码需要给前端写一个接口文档。
可以自动生成。

APIDOC

apidoc是一个简单的RESTful API文档生成工具，它从代码注释 中提取特定格式的内容生成文档。支持诸如GO、Java、C++、Rust 等大部分开发语言。

apidoc拥有以下特点

1.跨平台，linux. windows、 macOS等都支持;
2.支持语言广泛，即使是不支持，也很方便扩展;
3.支持多个不同语言的多个项目生成一份文档;
4.输出模板可自定义;
5.根据文档生成mock数据;

apidoc安装使用

• 安装：npm install -g apidoc
• 注释生成：
  apidoc根据注释生成文档，这就需要我们有好的注释规范。
  vscode有一个注释插件可以更方便的生成注释：ApiDoc Snippets
  
  
  生成模板之后在填入具体的注释信息。

eg：完成的注释：

/**
 * 
 * @api {post} /api/user user
 * @apiName addUser
 * @apiGroup usergroup
 * @apiVersion  1.0.0
 * 
 * 
 * @apiParam  {String} username 用户名
 * @apiParam  {String} password 密码
 * @apiParam  {Number} age 年龄
 * @apiParam  {File} avatar 头像
 * 
 * @apiSuccess (200) {number} ok 表示成功字段
 * 
 * @apiParamExample  {type} Request-Example:
 * {
 *     username : "yang",
 *     password:"123456",
 *     age:100,
 *     avatar:File
 * } 
 * 
 * @apiSuccessExample {type} Success-Response:
 * {
 *      ok:1
 * }
 * 
 */

• 生成文档命令：
  apidoc -i 要扫描的带注释的文档目录 -o 要生成的文档目录
  eg:
  apidoc -i src/ -o doc/
apidoc -i .\routes\ -o .\doc

执行命令生成的文档：

在浏览器打开index.html就可以查看生成的文档。

文档默认显示0.0.0要点击到1.0.0才会显示内容。
可以做相关配置，使文档直接显示1.0.0.
与doc平级新建apidoc.json文件，输入如下内容：（都可以自定义）

{
    "name":"后台系统接口文档",
    "version": "1.0.0",
    "description": "关于后台系统的接口文档描述",
    "title":" 企业网站定制系统"
}