APIDOC 初次使用记录
程序员文章站
2024-03-02 17:00:58
...
apidoc
是个文档生成工具 在你的控制层 写上注解 可以自动生成接口文档。 还可以测试。
步骤
1.先去node 官网下个node.js 网址:https://nodejs.org/en/
下他是因为apidoc依赖node.js的包管理工具npm 安装好node 就自动安装npm了
2.用终端 下载apidoc (我用cmd下的,node没搞懂。)
npm install apidoc -g
3.如果用的 cmd 输入 apidoc -h 出来一堆提示 教你怎么用的 就成功了。
4.打开你的项目 在你的项目根目录下 创建一个 apidoc.json 的文件
{
"name": "admin后台",
"version": "0.1.0",
"description": "admin后台接口文档",
"apidoc": {
"title": "Custom apiDoc browser title",
"url" : "http://xadmin.xiaozhitech.cn/"
}
}
name:名 version:版本 description:介绍 titile:标题 url:地址
5. 在你的controller 上 写注解
@api {请求方法:delete ,put, post,get} /地址 名称
@apiGroup 分组 你可以一个Controller 写成一个,显示的时候就在同一个分组里了。
@apiSuccessExample Success-Response: 返回的例子
@apiSampleRequest 这是你这个接口访问的 网址
/**
* @api {delete} /v1.0/tag 根据id删除标签
* @apiDescription 根据id删除标签
* @apiName delete
* @apiGroup Tag
* @apiVersion 1.0.0
*
* @apiParam {object} [tag] tag
*
* @apiSuccessExample Success-Response:
* {
* status: 200 //200 成功
* msg: "OK" // 返回信息消息
* data: null// 无返回数据
* }
*
* @apiSampleRequest http://xadmin.qa.xiaozhitech.cn/v1.0/tag
*
*/
@RequestMapping(value = "/tag", method = RequestMethod.DELETE, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
@ResponseBody
public XzResult deleteTag(Integer id) {
XzResult result = tagService.deleteTag(id);
return result;
}
6.运行项目吧, 然后打开 cmd cd到你创建的apidoc.json位置
-i 输入/源目录名。项目文件的位置 -o 输出目录名。文档放的位置
apidoc -i apidocInput/ -o apidocOutput/
(我偷懒用的 apidoc 直接生成到根目录下了。-.- 慌得一匹。)
终端显示 info:done 就完成了。上你设置的位置找去吧。
7. 就是下图这样的。
查不多就这样了,你如果写错注解的话,会在终端 报错的,具体因为啥,百度翻译就知道了。