java 自定义生成接口文档

文章目录

• 前言
• 相关技术简介

• OpenAPI
• Swagger
• Springfox
• springdoc
• swagger2与swagger3常用注解对比

• 实现步骤

• 引入maven依赖
• 修改配置文件
• 设置`api-docs`和`swagger-ui`访问权限
• 定义springdoc配置类
• 修改Controller类和实体类
• 查看效果

• 总结

前言

近日心血来潮想做一个开源项目，目标是做一款可以适配多端、功能完备的模板工程，包含后台管理系统和前台系统，开发者基于此项目进行裁剪和扩展来完成自己的功能开发。

本项目为前后端分离开发，后端基于Java21和SpringBoot3开发，后端使用Spring Security、JWT、Spring Data JPA等技术栈，前端提供了vue、angular、react、uniapp、微信小程序等多种脚手架工程。

本文主要介绍在SpringBoot3项目中如何整合springdoc-openapi实现自动生成在线接口文档，JDK版本是Java21。

项目地址：https://gitee.com/breezefaith/fast-alden

相关技术简介

OpenAPI

OpenAPI 规范（OAS），是定义一个标准的、与具体编程语言无关的RESTful API的规范。OpenAPI 规范使得人类和计算机都能在“不接触任何程序源代码和文档、不监控网络通信”的情况下理解一个服务的作用。如果您在定义您的 API 时做的很好，那么使用 API 的人就能非常轻松地理解您提供的 API 并与之交互了。

如果您遵循 OpenAPI 规范来定义您的 API，那么您就可以用文档生成工具来展示您的 API，用代码生成工具来自动生成各种编程语言的服务器端和客户端的代码，用自动测试工具进行测试等等。

参考文档：OpenAPI 规范 (中文版) https://openapi.apifox.cn/

Swagger

Swagger是一套围绕 Open API 规范构建的开源工具，可以帮助设计，构建，记录和使用 REST API。

Swagger工具包括的组件：

• Swagger Editor ：基于浏览器编辑器，可以在里面编写 Open API规范。类似 Markdown 具有实时预览描述文件的功能。
• Swagger UI：将 Open API 规范呈现为交互式 API 文档。用可视化UI 展示描述文件。
• Swagger Codegen：将 OpenAPI 规范生成为服务器存根和客户端库。通过 Swagger Codegen 可以将描述文件生成 html 格式和 cwiki 形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。
• Swagger Inspector：和 Swagger UI 有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。
• Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到 Swagger Hub 中。在 SwaggerHub 中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

使用 Swagger，就是把相关的信息存储在它定义的描述文件里面（yml 或 json 格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。

官方文档：https://swagger.io/

Springfox

Springfox是一套可以帮助Java开发者自动生成API文档的工具，它是基于Swagger 2.x基础上开发的，它遵循的是OpenAPI2.0（即Swagger2.0规范）。Swagger已经成为了RESTful API文档生态系统的事实标准，而Springfox是一个用于集成Swagger2.x到Spring应用程序中的库。而且Springfox提供了一些注解来描述API接口、参数和返回值，并根据这些信息生成Swagger UI界面，从而方便其他开发人员查看和使用您的API接口。

此外，Springfox还支持自动生成API文档和代码片段，简化了开发人员的工作量。除了集成Swagger 2.x，Springfox还提供了一些额外功能，例如自定义Swagger文档、API版本控制、请求验证等等。这些功能使得Springfox可以胜任各种类型和规模的应用程序，同时还可以提高代码质量和开发效率。

总之，Springfox是一个非常有用的工具，它可以帮助Java开发者快速、简单地集成Swagger2.x，并为他们的应用程序生成高质量的API文档。无论您开发的是大型企业应用程序还是小型服务，使用Springfox都能够提高团队的生产力和代码质量。

官方文档：https://springfox.github.io/springfox/

springdoc

SpringDoc是基于OpenAPI 3.0规范构建的，因此推荐在Spring Boot 2.4及以上版本中使用springdoc-openapi-ui库来集成Swagger3.x。在这些版本中，springdoc-openapi-ui库已被广泛应用，并且得到了社区的大力支持和推广。而在Spring Boot 2.3及其以下版本，可以使用springfox-boot-starter库来集成Swagger2.x。

SpringDoc有着更加先进的技术架构和更好的扩展性，使得其逐渐取代了springfox-boot-starter工具包，成为了当前Spring Boot生态中最受欢迎的API文档工具之一。同时springdoc-openapi-ui还拥有更为完善的开发文档和社区支持，从而吸引了越来越多的开发者加入到这个项目中。因此作为一个Spring Boot开发者，如果想要快速、方便地生成符合OpenAPI 3.0规范的接口文档，建议使用springdoc-openapi-ui这个优秀的工具。

官方文档：https://springdoc.org/

swagger2与swagger3常用注解对比

swagger2	swagger3	注解位置
@Api	@Tag(name = “接口类描述”)	Controller 类
@ApiOperation	@Operation(summary =“接口方法描述”)	Controller 方法
@ApiImplicitParams	@Parameters	Controller 方法
@ApiImplicitParam	@Parameter(description=“参数描述”)	Controller 方法的 @Parameters 里
@ApiParam	@Parameter(description=“参数描述”)	Controller 方法的参数上
@ApiIgnore	@Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden	-
@ApiModel	@Schema	DTO类上
@ApiModelProperty	@Schema	DTO属性上

实现步骤

引入maven依赖

在pom.xml中添加springdoc-openapi-starter-webmvc-ui以及相关依赖。

<dependencies>
  <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
  </dependency>
  <!-- 项目中使用了spring-security时可以引入此依赖 -->
  <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-security</artifactId>
    <version>1.7.0</version>
  </dependency>
  <!-- 如果使用的是spring webflux而非spring-webmvc，则需要将springdoc-openapi-starter-webmvc-ui改为如下依赖 -->
  <!-- <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.3.0</version>
  </dependency> -->
</dependencies>

修改配置文件

在application.yml中可以自定义api-docs和swagger-ui的访问路径。

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html

设置api-docs和swagger-ui访问权限

如果项目中启用了权限控制，需要合理设置api-docs和swagger-ui相关资源的访问权限。比如笔者使用的spring-security，将api-docs和swagger-ui相关资源设置为允许匿名访问，不需要认证授权。

@Configuration
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        // 将api-docs和swagger-ui相关资源设置为允许匿名访问
        http.authorizeHttpRequests((authorizationManagerRequestMatcherRegistry) -> {
			authorizationManagerRequestMatcherRegistry.requestMatchers("/v3/api-docs").permitAll();
			authorizationManagerRequestMatcherRegistry.requestMatchers("/v3/api-docs/**").permitAll();
			authorizationManagerRequestMatcherRegistry.requestMatchers("/swagger-ui.html").permitAll();
			authorizationManagerRequestMatcherRegistry.requestMatchers("/swagger-ui/**").permitAll();
        
            // 其余资源登录后方可访问
            authorizationManagerRequestMatcherRegistry.anyRequest().authenticated();
        });
    	
        // 其余spring security配置已省略
        // ...
        
        return http.build();
    }
}

定义springdoc配置类

@Configuration
public class SpringDocConfig {
    /**
     * 一个自定义的 OpenAPI 对象
     *
     * @return 一个自定义的 OpenAPI 对象
     */
    @Bean
    public OpenAPI customOpenApi() {
        return new OpenAPI()
        .components(new Components()
                    // 设置 spring security jwt accessToken 认证的请求头 Authorization: Bearer xxx.xxx.xxx
                    .addSecuritySchemes("openApiSecurityScheme", new SecurityScheme()
                                        .type(SecurityScheme.Type.HTTP)
                                        .bearerFormat("JWT")
                                        .in(SecurityScheme.In.HEADER)
                                        .name("Authorization")
                                        .scheme("Bearer")))
        // 设置标题、版本等信息
        .info(new Info()
              .title("Fast Alden权限管理系统")
              .version("0.0.1-SNAPSHOT")
              .description("")
              .license(new License()
                       .name("Apache 2.0")
                       .url("https://www.apache.org/licenses/LICENSE-2.0.html")));
    }
}

在上述代码中定义了一个key为openApiSecurityScheme的SecuritySchemes，在后续章节的Controller类中使用。

修改Controller类和实体类

在Controller类和实体类中添加swagger相关注解。

• @Tag 用于标识controller
• @Operation 用于标识方法
• @Schema 用于标识实体类和实体类的属性
• @ApiResponse 用于标识请求的响应
• @Parameters和@Parameter 用于标识请求参数，@Parameter的name需要和变量的命名一致，@Parameter要放到函数形参前面

以下代码中@Operation注解通过security属性指定认证方式，openApiSecurityScheme已在上文springdoc配置类中声明。

1. SysUserController.java

// SysUserController.java
@Tag(name = "SysUserController", description = "后台用户管理")
@RestController
@RequestMapping("/user")
public class SysUserController {
    @Resource
    private SysUserService userService;

    @Operation(summary = "根据ID查询", security = @SecurityRequirement(name = "openApiSecurityScheme"))
    @GetMapping("/retrieve/{id}")
    public SysUser retrieve(@PathVariable("id") Long id) {
        return userService.retrieve(id);
    }

    @Operation(summary = "创建用户", security = @SecurityRequirement(name = "openApiSecurityScheme"))
    @PostMapping("/create")
    public Long create(@RequestBody SysUser user) {
        return userService.create(user).getId();
    }

    @Operation(summary = "修改用户", security = @SecurityRequirement(name = "openApiSecurityScheme"))
    @PutMapping("/update")
    public void update(@RequestBody SysUser user) {
        userService.update(user);
    }

    @Operation(summary = "删除用户", security = @SecurityRequirement(name = "openApiSecurityScheme"))
    @DeleteMapping("/remove")
    public void remove(@RequestParam("ids") List<Long> ids) {
        userService.remove(ids);
    }
}

2. SysUser.java

// SysUser.java
/**
 * 用户实体类
 */
@Getter
@Setter
@Schema(description = "用户")
public class SysUser {
    @Schema(description = "用户ID")
    private Long id;

    @Schema(description = "用户名")
    private String username;

    @Schema(description = "密码")
    private String password;

    @Schema(description = "电话")
    private String phone;

    @Schema(description = "个人介绍")
    private String introduce;

    @Schema(description = "所属部门ID")
    private Long departmentId;
}

查看效果

1. 访问 http://localhost:8080/v3/api-docs可获取JSON格式的API文档。

2. 访问 http://localhost:8080/swagger-ui.html可直接在线测试API，在Authorize弹窗中可以填入token用于模拟在线用户。

总结

本文简单介绍了一下OpenAPI、Swagger、Springfox和SpringDoc的相关概念，以及详细介绍了SpringBoot3整合SpringDoc的完整过程，如有错误，还望批评指正。

在后续实践中我也是及时更新自己的学习心得和经验总结，希望与诸位看官一起进步。