Springboot项目使用apidoc生成接口文档

 

1.前言

1.为什么需要接口文档

1. 当前后端分离时，需要前后端共同定义接口，编写接口文档。所以，在项目开发过程中需要有一个统一的文件进行沟通交流开发。
2. 对开发人员而言，项目的维护和人员更迭，都需要文档来作为记录。方便后期人员查看、维护。

2.apidoc能做什么

apidoc是一个轻量级的在线REST接口文档生成系统，可以根据其特定的规则的代码注释来生成静态网页。首先看下它生成的文档界面和风格。

支持
apidoc支持多种主流的编码语言，包括Java、C、C#、php和javascript。一般情况下，语言会有多种注释方法，例如就Java中有普通风格的多行注释和Javadoc风格的注释。apidoc并不支持所有的注释，譬如Java仅中支持Javadoc风格的注释。首先要说明的是，apidoc并不具备语义识别能力，它不会发现代码中是否有BUG，它仅仅通过文件后缀来判断语言类型。

3.有哪些常用的API自动生成文档工具

1. swagger 这款工具感觉是最常用的一款自动生成文档的工具。
   附上官网地址：https://swagger.io/
2. apidoc。第一次见到这个api文档是在公司的cmdb的接口文档中看见，个人比较喜欢这种风格的。
   附上github地址：https://github.com/apidoc/apidoc

2.使用前的准备工作

1.确认当前电脑安装了node.js。检测是否安装

node -h

• 出现提示，表明已经安装node.js。如果没有，需要安装node.js

2.安装apidoc

npm install apidoc -g

3.然后再测试一下apidoc是否安装成功

apidoc -h

• 出现提示则为，安装成功

3.springboot项目中使用apidoc

1.首先准备一个空的springboot的项目。

2.在项目中新建package.json 文件

位置如下图所示：

package.json 文件内容：

{
  "name": "测试api文档",
  "version": "0.1.0",
  "description": "这只是一个测试的页面",
  "title": "APIDOC 测试",
  "url" : "https://127.0.0.1:8080/",
 
}

 

4.方法接口前加上注释：

@Autowired
    private MemberListService memberListService;
    /**
     * @api {get} /memberlist/:会员用户列表
     * @apiDescription  会员用户列表展示
     * @apiName memberlist
     * @apiParam {String} phoneNo 用户的电话
     * @apiParamExample {json} Request-Example:
     * {
     *     "phoneNo":"15713669254"
     * }
     * @apiGroup memberlist
     * @apiSampleRequest /memberlist
     */

    @RequestMapping("/memberlist")
    public List<UserCouponRecord> memberList(String phoneNo){
        return  memberListService.getMemberList(phoneNo);
    }

很简单，直接在方法上面加入注释，在注释中使用官方的一些注解来解释方法的属性。

5.生成文档

apidoc 和 swagger不同的是，接口文档和代码文件都是分开的。一开始只需要专心编写接口代码，当代码编写完成时，只需在方法上加上指定的注释。（到这里，也就是我上述所描述的内容）。最终通过一段命令执行生成最终的html文档。
回归正题，在准备工作中我们已经安装了apidoc，然后我们通过apidoc命令生成文档：

apidoc -i apiTestDemo/ -o apidocDemo/

• 1

结果：

-i 指定源文件的目录，也就是项目的根目录。
-o 指定输出 文档的目录，生成文档的地址。
页面展示：
最后打开打开index 页面：

参考博客：https://blog.csdn.net/a704397849/article/details/100560342

https://blog.csdn.net/bicheng4769/article/details/83088827