java快速生成接口文档方法总结

古城微笑少年丶 2022-09-01 09:21 307阅读 0赞

## 前言 ##

常常在项目收尾阶段，客户需要项目的接口文档，或者是一个大的sass平台，各个产品之间互相调用的时候，需要对方提供接口文档

通常来说，接口文档属于产品的技术沉淀，是一个长期积累的过程，然而，很多时候，开发阶段并不会想的那么多，结果到了需要接口文档的时候总是疲于应付，情急之下，往往采用最笨拙的办法，就是对照着项目代码，一个个拷贝吧

下面针对这个情况，小编这里给出2种简单、快捷而适用的解决方案，帮助你快速解决这个烦恼吧

## 方案一，使用japidocs ##

这是一种最简单也最高效的快速生成接口文档的方式，也是对既有项目改造代价最小的方式

*  可用于生成spring boot api文档
 *  读取JAVA DOC注释，无需额外的代码改造

**基本用法**

**1、添加依赖**

<dependency>
                <groupId>io.github.yedaxia</groupId>
                <artifactId>japidocs</artifactId>
                <version>1.4.3</version>
            </dependency>

**2、在工程的某个包下面，添加一个类**

![在这里插入图片描述][f74e22c17fe9475cb620a071a56d98ee.png]  
如这里有一个TestApi的类，里面添加一个main方，使用如下模板代码即可，自己使用时，需要简单修改几处，项目根目录，生成文档的目录

public class TestApi {
    
        public static void main(String[] args) {
            DocsConfig config = new DocsConfig();
            // 项目根目录
            config.setProjectPath("E:\\学习代码\\assmblyone\\web");
            // 项目名称
            config.setProjectName("Assembly");
            // 声明该API的版本
            config.setApiVersion("V2.0");
            // 生成API 文档所在目录
            config.setDocsPath("E:\\学习代码\\assmblyone");
            // 配置自动生成
            config.setAutoGenerate(Boolean.TRUE);
            // 执行生成文档
            Docs.buildHtmlDocs(config);
        }
    
    }

这里假如工程中有一个UserController接口类

@RestController
    @RequestMapping(value = "/api2doc")
    public class UserController {
    
        /**
         * 获取用户讯息
         * @return
         */
        @ApiComment("获取用户。")
        @GetMapping("/getUser")
        public User getUser() {
            User user = new User();
            user.setGroup("group1");
            user.setName("first-group");
            return user;
        }
    
        /**
         * 新增用户
         * @param group 用户组名称
         * @param name  基础名称
         * @return
         */
        @ApiComment("添加新用户")
        @GetMapping(name = "新增用户", value = "/user")
        public String addUser(String group, String name) {
            return " group:" + group + " ==== " + "name :" + name;
        }
    
    }

有一个实体类User

@Data
    public class User {
    
        /**
         * id主键
         */
        private Long id;
    
        /**
         * 用户名
         */
        private String name;
    
        /**
         * 账号密码
         */
        private String password;
    
        /**
         * 用户所在的组
         */
        private String group;
    
        /**
         * 用户类型
         */
        private UserType type;
    
        /**
         * 是否已删除
         */
        private Boolean deleted;
    
        /**
         * 创建时间
         */
        private Date createTime;
    
    }

> 为了让生成的文档看起来更加完善，controller的各个接口名称，以及实体中的字段等注释一定要尽可能完整

然后运行一下main方法，生成一下吧  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nY29uZ3lpNDIw_size_16_color_FFFFFF_t_70]

然后会发现，在指定的文件目录下，针对项目中的各个controller类，生成了html文档，不妨打开看一下吧

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nY29uZ3lpNDIw_size_16_color_FFFFFF_t_70 1]

这个效果也算很良心了，到这里是不是值得小小庆贺下呢,当然对于japidocs来说，功能可不止这些，有兴趣的同学可以继续深入研究下呢

## 方案2，swagger + knife4j ##

相信使用过springboot框架的同学对swagger插件一定不陌生，springboot中集成swagger 可以帮助我们快速进行接口调试，以提升开发人员的接口调试效率

但是单纯使用swagger的话，效果往往并不理想，比如想使用swagger导出一份可以交付的接口文档的话，就有点困难了，这就需要swagger 配合knife4j一起使用了

**生成步骤**

**1、导入相关依赖**

<dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>knife4j-spring-boot-starter</artifactId>
                <version>2.0.4</version>
            </dependency>
    		
    		
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>${swagger.version}</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>${swagger.version}</version>
            </dependency>
            <dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>swagger-bootstrap-ui</artifactId>
                <version>${swagger-bootstrap-ui.version}</version>
            </dependency>

**2、添加swagger配置类**

@Configuration
    @EnableSwagger2
    @EnableKnife4j
    public class ApiSwagger2 {
    
        @Bean
        public Docket createRestBmbsApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("users")
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.congge.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("用户相关API")
                    .version("1.0")
                    .build();
        }
    
    }

**3、启动项目之后分别访问如下地址**

http://localhost:8048/swagger-ui.html  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nY29uZ3lpNDIw_size_16_color_FFFFFF_t_70 2]

这个界面想必大家一定很熟悉了，这就是swagger界面，可以在这个上面快速进行接口调试工作

http://localhost:8048/doc.html\#/home  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nY29uZ3lpNDIw_size_16_color_FFFFFF_t_70 3]

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nY29uZ3lpNDIw_size_16_color_FFFFFF_t_70 4]

这个界面就是集成了knife4j之后展示出来的效果，这个效果看起来是不是更好了点

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nY29uZ3lpNDIw_size_16_color_FFFFFF_t_70 5]

点就到文档管理菜单栏，提供了几种常用的可用于下载的接口文档方式，比如我们以html为例，点击下载，然后看一下效果如何  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nY29uZ3lpNDIw_size_16_color_FFFFFF_t_70 6]

## 方案3，开源的接口文档生成工具 ##

这里推荐2种

**1、japi ，这是一个开源项目，git上面可以下载之后本地运行，需要安装node环境**

这里推荐一篇文章，可供参考：https://www.jianshu.com/p/8ac211d9c6d3

**2、使用ApiPost工具快速生成在线接口文档**

ApiPost是一个支持团队协作，并可直接生成文档的API调试、管理工具。它支持模拟POST、GET、PUT等常见请求，是后台接口开发者或前端、接口测试人员不可多得的工具 。使用者不仅可以利用apiopst调试接口，还可以书写相关注释（接口文档），方便的生成可读性好、界面美观的在线接口文档。

使用ApiPost需要下载官方安装包，然后本地安装即可，官网软件下载地址：https://www.apipost.cn/

关于ApiPost，由于其功能的强大，被很多开发人员，测试人员以及项目管理人员等广泛使用，在小编所在的产品测试团队，不少测试同事使用这款工具

对小编来说，所有麻烦的事情一律都采用保守的态度，但是这款工具确实值得推荐和学习，界面风格很相PostMan，这里有一篇详细介绍ApiPost使用的文档，提供参考和学习：https://www.cnblogs.com/gina61/articles/12931356.html

[f74e22c17fe9475cb620a071a56d98ee.png]: /images/20220829/fd332e63796e429aa1e9fca968427a98.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nY29uZ3lpNDIw_size_16_color_FFFFFF_t_70]: /images/20220829/ad828569834f429a9904324af83d1c97.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nY29uZ3lpNDIw_size_16_color_FFFFFF_t_70 1]: /images/20220829/84644e297aef463d9b1cecf38844b7a5.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nY29uZ3lpNDIw_size_16_color_FFFFFF_t_70 2]: /images/20220829/384a7bec40d54789bba7e0d86d40fa71.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nY29uZ3lpNDIw_size_16_color_FFFFFF_t_70 3]: /images/20220829/4226815072ce4336a47a181405f4cadf.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nY29uZ3lpNDIw_size_16_color_FFFFFF_t_70 4]: /images/20220829/e9ef6685de91486ead17136c7a8576e9.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nY29uZ3lpNDIw_size_16_color_FFFFFF_t_70 5]: /images/20220829/93efcc11b66242e983242f9271913b83.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nY29uZ3lpNDIw_size_16_color_FFFFFF_t_70 6]: /images/20220829/9bbe0537092b4d7b8212c5bf180cc1b3.png