简介
APIdoc是一个接口文档,他跟Swagger的区别如下:
- APIDOC可以离线查看,Swagger必须运行查看。
- APIDOC生成文档复杂,Swagger生成文档很简单。
综上考虑,如果需要离线环境看文档的,还是推荐APIdoc,如果有条件线上查看的,十分推荐Swagger,因为它太省事啦!!
APIdoc长这样
下载APIdoc
首先你需要安装有node.js的环境(没有就下载个)
打开项目,在终端运行如下
npm intsall apidoc //安装apidoc
在根目录创建apidoc.json配置文件
apidoc.json内容如下
{
"name": "闲置物品商城接口文档",
"version": "0.0.1",
"description": "闲置物品商城接口文档",
"title": "闲置物品商城",
"url": "http://127.0.0.1:8080",
"sampleUrl": "http://127.0.0.1:8080"
}
使用
在需要生成接口文档的方法上写上注释,例子如下
/**
* @api {post} /article/add 发布文章
* @apiVersion 0.0.1
* @apiDescription 用户发布文章的接口
* @apiGroup Article-文章
* @apiParam(入参) {int} userId 文章的用户id(系统生成唯一,在用户登录时返回),必填
* @apiParam(入参) {String} articleTitle 文章标题,必填
* @apiParam(入参) {text} articleContent 文章内容,必填
* @apiParam(入参) {text} abbreviatedContent 收起的缩略内容
* @apiParam(入参) {String} articleCoverUrl 文章封面(调用图片上传接口),选填
* @apiParam(入参) {int} declare 创作声明,暂分类为:0:无声明(默认); 1:虚假创作; 2: 包含理财内容; 3: 包含剧透;4:包含医疗建议;
* @apiParam(入参) {array} tagList 标签列表,至少带一个,文章带的话题是个标签,所属分类是话题
* @apiParam(入参) {int} tagId 标签id,值列表,需数据库中拥有。
* @apiParamExample {json} 入参样例:
* {
* "userId": 1,
* "articleTitle": "100个英语词组",
* "articleContent": "<p>xxx</p >",
* "abbreviatedContent": "xxx",
* "articleCoverUrl": "http://10.12.0.158:8383/imagesUpload/478ce7df-b69d-43ae-804c-4f6d7eca83d0.jpg",
* "declare": 1,
* "tagList": [
* {
* "tagId": 1
* },
* {
* "tagId": 2
* }
* ]
* }
*
* @apiSuccess(出参) {String} Code 接口返回编码;200-添加成功;2001-数据库执行有异常;
* @apiSuccess(出参) {String} Message 消息描述
* @apiSuccess(出参) {object} data 添加对象
*
* @apiSuccessExample {json} 返回成功样例:
* {
* "code": 200,
* "message": "添加成功",
* "data": {
* "articleId": 2,
* "userId": 1,
* "articleTitle": "100个英语词组",
* "articleContent": "<p>xxx</p >",
* "linkName": null,
* "linkUrl": null,
* "declare": 1,
* "introduce": null,
* "isPush": null,
* "isAllowed": null,
* "isRestriction": null,
* "restrictionType": null,
* "agreeNumber": null,
* "disagreeNumber": null,
* "commentNumber": null,
* "mark": null,
* "createTime": "2021-11-04 23:16:05",
* "updateTime": null,
* "isDelete": null,
* "articleCoverUrl": "http://10.12.0.158:8383/imagesUpload/478ce7df-b69d-43ae-804c-4f6d7eca83d0.jpg",
* "abbreviatedContent": "xxx",
* "tagList": [
* {
* "tagId": 1
* },
* {
* "tagId": 2
* }
* ]
* }
* }
* @apiErrorExample {json} 返回失败样例:
* {
* "code": 2001,
* "message": "数据库执行有异常",
* "data": null
* }
* @return
*/
@PostMapping(value = "/add")
public CommonResult addArticle(@RequestBody String json) throws Exception{
System.out.println("addArticle==>"+json);
//转化为实体类
Article article = JSON.parseObject(json, Article.class);
return articleService.insert(article);
}
配置完成后就可以使用啦!在终端输入apidoc -i src -o apidoc
可以发现在根目录多了个“apidoc”的文件夹,里面就是你的接口文档啦
附言
注解 | 含义 |
---|---|
@apiVersion | 接口版本 |
@apiDescription | 接口具体说明 |
@apiGroup | 接口所属分组 |
@apiParam | 入参 |
@apiParamExample | 入参样例 |
@apiSuccess | 出参 |
@apiSuccessExample | 返回成功样例 |
@apiErrorExample | 返回失败样例 |