接口文档————Apidoc的使用

简介

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	返回失败样例