使用apidoc来编写restful接口api文档

使用apidoc来编写restful接口api文档

apidoc需要环境

​ apidoc运行需要nodeJs环境，由于nodeJs的环境安装与配置文档很多，如果电脑上还没有nodeJs环境，请自行百度配置环境。

https://www.baidu.com/

​ nodeJs安装完成后可以，使用node -v 和 npm -v检验是否安装成功，如果安装成功会出现如下图所示：

apidoc使用配置

​ 安装apidoc

npm install apidoc -g

​ 查看apidoc是否安装成功

apidoc -h

​ 生成文档必须有.json 文件和带有Javadoc风格注释(可以在C#, Go, Dart, Java, JavaScript, PHP, TypeScript等语言中使用)的文件。

​ apidoc.json

{
  "name": "Model-Service API",
  "version": "0.1.0",
  "description": "行为建模服务端接口",
  "title": "Model-Service API",
  "url": "http://192.168.1.104:9199/model-service",
  "template": {
    "forceLanguage": "zh_cn",
    "withCompare": true,
    "withGenerator": true
  }
}

在项目中可以单独设立一个模块用来用于文档的生成：

apidoc的使用

使用apidoc生成接口文档时最好将controller层的代码提出来修改为.js文件，并放在src下，然后就可以写一些apidoc的注解。

/**
 * @api {post} /auth/login  1. 登录
 * @apiVersion 0.1.0
 * @apiName Auth_Login
 * @apiGroup 账号管理
 *
 * @apiDescription 使用账号、密码登录
 *
 * @apiParam {String} username 账号
 * @apiParam {String} password 密码
 *
 * @apiParamExample 请求参数
 * username=admin&password=123456
 *
 * @apiSuccessExample {json} 响应结果
{
    "status": 200,
    "message": "成功",
    "data": {
        "token": "eyJ1aWQiOjEyOTE2MjQ2NDU3MTIwNTIyMjQsImFsZyI6IkhTMjU2IiwidHlwIjoiSldUIn0.eyJpc3MiOiJodHRwOi8vd3d3LmJsdWV0aGluay5jbiIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2IiwiaWF0IjoxNTk3MDQ1MDY1fQ.DjaO5uHrIj0CumIDUHXK5YBb3cGR5ka1Y0Hn3D3tTP8"
    },
    "timestamp": "2020-08-10 15:37:45"
}
 */
function login() {  }

执行语句生成接口文档

apidoc -i src/ -o doc/

语句执行后生成的接口文档

总结

本文在于记录使用apidoc生成接口文档的一次过程，随笔记录。