Java接口文档生成工具太牛了！java生成接口文档的三种解决方案

知梧 733 2022-09-08


本文关于Java接口文档生成工具太牛了！java生成接口文档的三种解决方案。

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

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

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

方案一，使用japidocs

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

  • 可用于生成spring boot api文档

  • 读取JAVA DOC注释，无需额外的代码改造

基本用法

1、添加依赖

1
2
3
4
5
<dependency>
    <groupId>io.github.yedaxia</groupId>
    <artifactId>japidocs</artifactId>
    <version>1.4.3</version>
</dependency>

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

在这里插入图片描述

如这里有一个TestApi的类，里面添加一个main方，使用如下模板代码即可，自己使用时，需要简单修改几处，项目根目录，生成文档的目录

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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接口类

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
@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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
@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方法，生成一下吧

在这里插入图片描述

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

在这里插入图片描述

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

方案2，swagger + knife4j

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

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

自媒体培训

生成步骤

1、导入相关依赖

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.4</version>
</dependency>
 
<!--swagger-ui-->
<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配置类

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
@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

在这里插入图片描述

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

http://localhost:8048/doc.html#/home

在这里插入图片描述

在这里插入图片描述

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

在这里插入图片描述

点就到文档管理菜单栏，提供了几种常用的可用于下载的接口文档方式，比如我们以html为例，点击下载，然后看一下效果如何

在这里插入图片描述

方案3，接口文档生成工具

这里推荐2种

1、Eolink

Eolinker是国内团队自主研发的，主要支持以下功能：
•   可视化接口管理
•   数据mock
•   自动化接口测试
•   数据导入（各种，包括swagger、har、postman、json、命令行）
•   权限管理
•   支持本地化部署
•   支持插件
•   支持二次开发
优点：功能非常强大，支持权限管理、在线调试、接口自动化测试、插件开发等，拓展性也很好。

缺点：是Saas管理工具，没有源码。
个人建议：如果需求比较复杂，这个在线文档工具还是非常好用的，笔者在这里强烈推荐一下。

2、ApiPost

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

上述就是小编为大家整理的Java接口文档生成工具太牛了！java生成接口文档的三种解决方案。

国内(北京、上海、广州、深圳、成都、重庆、杭州、西安、武汉、苏州、郑州、南京、天津、长沙、东莞、宁波、佛山、合肥、青岛)eolink软件分析、比较及推荐。




版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。

标签：接口开发 接口文档 接口管理 api
上一篇:NLM5系列无线振弦传感采集仪的工作模式及休眠模式下状态
下一篇:什么样的网站需要办理ICP？（开通网站需要什么条件）
相关文章

 发表评论

暂时没有评论，来抢沙发吧~