使用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生成接口文档的一次过程,随笔记录。