apiDoc 使用指南
安装
- 安装node.js
- 安装apiDoc
npm install apidoc -g
配置
在你的项目根目录下新建apidoc.json文件,该文件描述了项目对外提供接口的概要信息如名称、版本、描述、文档打开时浏览器显示标题和接口缺省访问地址。
apidoc.json
{
"name": "ServiceEbikeAPIs",
"version": "3.1.0",
"description": "车辆服务接口文档",
"title": "ServiceEbikeAPIs",
"url" : "http://cjl3.rokyinfo.net:7190/api-ebike"
}
使用样例
/**
*
* @apiDefine RkNotFoundException
*
* @apiError RkNotFoundException 找不到相关数据
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": {
* "code": 404,
* "msg": "",
* "path" ""
* }
* }
*
*/
/**
*
* @api {get} /v3.1/ues/:sn/rt-info 获取设备上报实时信息
* @apiVersion 3.1.0
* @apiName GetUeRealTimeInfo
* @apiGroup UE
*
* @apiHeader {String} Authorization 用户授权token
* @apiHeader {String} firm 厂商编码
* @apiHeaderExample {json} Header-Example:
* {
* "Authorization": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOjM2NzgsImF1ZGllbmNlIjoid2ViIiwib3BlbkFJZCI6MTM2NywiY3JlYXRlZCI6MTUzMzg3OTM2ODA0Nywicm9sZXMiOiJVU0VSIiwiZXhwIjoxNTM0NDg0MTY4fQ.Gl5L-NpuwhjuPXFuhPax8ak5c64skjDTCBC64N_QdKQ2VT-zZeceuzXB9TqaYJuhkwNYEhrV3pUx1zhMWG7Org",
* "firm": "cnE="
* }
*
* @apiParam {String} sn 设备序列号
*
* @apiSuccess {String} sn 设备序列号
* @apiSuccess {Number} status 设备状态
* @apiSuccess {Number} soc 电池电量百分比
* @apiSuccess {Number} voltage 电池电压
* @apiSuccess {Number} current 电池电流
* @apiSuccess {Number} temperature 电池温度
* @apiSuccess {String} reportTime 上报时间(yyyy-MM-dd HH:mm:ss)
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "sn": "P000000000",
* "status": 0,
* "soc": 80,
* "voltage": 60.0,
* "current": 10.0,
* "temperature": null,
* "reportTime": "2018-08-13 18:11:00"
* }
*
* @apiUse RkNotFoundException
*
*/
@RequestMapping(value = "/{sn}/rt-info", method = RequestMethod.GET)
public UeRealTimeInfo getUeRealTimeInfo(@RequestHeader(Constants.HEADER_LOGIN_USER_KEY) long userId, @PathVariable("sn") String sn) {
return ueService.getRealTimeInfo(sn);
}
@api
@api {method} path [title]
HTTP接口调用方法、路径及名称
@apiVersion
@apiVersion version
api 版本号
@apiName
@apiName name
api 名称
@apiGroup
@apiGroup name
api 分组
@apiHeader
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
请求头参数
@apiParam
@apiParam [(group)] [{type}] [field=defaultValue] [description]
请求参数
@apiSuccess
@apiSuccess [(group)] [{type}] field [description]
返回数据描述
@apiSuccessExample
@apiSuccessExample [{type}] [title]
example
接口成功返回样例
@apiError
@apiError [(group)] [{type}] field [description]
接口失败描述
@apiErrorExample
@apiErrorExample [{type}] [title]
example
接口失败返回样例
@apiDefine
@apiDefine name [title]
[description]
类似于宏定义,可以被引用
@apiUse
@apiUse name
使用@apiDefine定义的描述
更详细的说明请参考官方文档http://apidocjs.com
生成文档
cd到apidoc.json所在路径(即项目根目录)执行如下命令即可
apidoc -i src/ -o apidoc/
执行成功后会生成apidoc文件夹如下图所示
图片
点开apidoc文件夹中index.html会发现已经生成的漂亮的api文档
【推荐】国内首个AI IDE,深度理解中文开发场景,立即下载体验Trae
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· Linux系列:如何调试 malloc 的底层源码
· AI与.NET技术实操系列:基于图像分类模型对图像进行分类
· go语言实现终端里的倒计时
· 如何编写易于单元测试的代码
· 10年+ .NET Coder 心语,封装的思维:从隐藏、稳定开始理解其本质意义
· 25岁的心里话
· 闲置电脑爆改个人服务器(超详细) #公网映射 #Vmware虚拟网络编辑器
· 因为Apifox不支持离线,我果断选择了Apipost!
· 零经验选手,Compose 一天开发一款小游戏!
· 通过 API 将Deepseek响应流式内容输出到前端