SpringDoc OpenAPI集成spring boot3

SpringDoc OpenAPI集成spring boot3

一、简介

SpringDoc OpenAPI 是一个基于 OpenAPI 3 规范的 Java 库，用于自动生成 Spring Boot 应用的 API 文档。它是 Springfox Swagger 的替代品，具有以下优势：

1. 官方推荐：Spring 团队推荐的 API 文档解决方案
2. 零配置：自动发现 Spring MVC 端点，无需复杂配置
3. 性能更好：启动速度比 Springfox 快
4. 支持最新标准：完整支持 OpenAPI 3.0 规范
5. 丰富功能：支持 Spring WebFlux、Spring Security 等

二、实操

1、Pom依赖：

如果你的项目用的是web-services

有这样的依赖：

那么使用

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.8.13</version>
</dependency>

如果你是流式响应：

那么使用；

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.8.13</version>
</dependency>

2、application.properties配置

# Swagger
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.api-docs.path=/v3/api-docs

3、配置文件

新建OpenApiConfig文件
 

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("API 文档")
                        .version("2.0")
                        .description("基于 SpringDoc OpenAPI 2.8.13 的接口文档")
                        .license(new License()
                                .name("Apache 2.0")
                                .url("https://springdoc.org")));
    }
}

如配置了Security则需要配置放行

public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
    // SpringDoc OpenAPI 相关的放行路径
    String[] openApiPaths = {
            "/swagger-ui.html",
            "/swagger-ui/**",
            "/v3/api-docs/**",
            "/swagger-resources/**",
            "/webjars/**",
            "/favicon.ico"
    };

    return http
            .csrf(ServerHttpSecurity.CsrfSpec::disable)
            .authorizeExchange(exchanges -> exchanges
                    // 放行 OpenAPI 相关路径
                    .pathMatchers(openApiPaths).permitAll()
                    // 放行你的前端 API 路径
                    .pathMatchers("/**").permitAll()
                    // 其他路径需要认证
                    .anyExchange().authenticated()
            )
            .httpBasic(ServerHttpSecurity.HttpBasicSpec::disable)
            .formLogin(ServerHttpSecurity.FormLoginSpec::disable)
            .build();
}

4、控制层设置信息

@RestController

@Tag(name = "用户管理", description = "用户相关操作API")

@RequestMapping("/api/users")

public class UserController {

   

    @Operation(summary = "获取用户列表", description = "返回所有用户信息")

    @GetMapping

    public List<User> getAllUsers() {

        // 实现

    }

   

    @Operation(summary = "创建用户", description = "创建新用户")

    @ApiResponses({

        @ApiResponse(responseCode = "201", description = "用户创建成功"),

        @ApiResponse(responseCode = "400", description = "无效输入")

    })

    @PostMapping

    public ResponseEntity<User> createUser(

            @Parameter(description = "用户对象", required = true)

            @RequestBody User user) {

        // 实现

    }

}

5、实体类中设置信息

@Schema(description = "用户实体")

public class User {

   

    @Schema(description = "用户ID", example = "1")

    private Long id;

   

    @Schema(description = "用户名", required = true, example = "john_doe")

    private String username;

   

    @Schema(description = "邮箱地址", format = "email")

    private String email;

   

    // getters/setters

}

启动springboot项目后，控制台会打印出以下，证明OpenApi 服务启动

在浏览器访问

https://localhost:9000/swagger-ui/index.html

如果没有配置ssl

就访问

http://localhost:9000/swagger-ui/index.html

如图，集成成功

三、分组配置

在OpenApiConfig文件，

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                    .title("API 文档")
                    .version("2.0")
                    .description("基于 SpringDoc OpenAPI 2.8.13 的接口文档")
                    .license(new License()
                            .name("Apache 2.0")
                            .url("https://springdoc.org")))

            // === 关键：配置Swagger UI的分组下拉框 ===
            .extensions(Map.of(
                    "x-group-config", Map.of(
                            "urls", List.of(
                                    Map.of("name", "删除操作", "url", "/v3/api-docs/delete-api"),
                                    Map.of("name", "聊天操作", "url", "/v3/api-docs/chat-api")
                            )
                    )
            ));
}

// === 分组配置 ===
@Bean
public GroupedOpenApi deleteApiGroup() {
    return GroupedOpenApi.builder()
            .group("delete-api") // 分组标识（URL用）
            .displayName("删除操作") // UI显示名称（中文）
            .pathsToMatch("/chat/delete/**") // 匹配删除接口
            .build();
}

@Bean
public GroupedOpenApi chatApiGroup() {
    return GroupedOpenApi.builder()
            .group("chat-api") // 分组标识（URL用）
            .displayName("聊天操作") // UI显示名称（中文）
            .pathsToMatch("/chat/**") // 匹配所有聊天接口
            .pathsToExclude("/chat/delete/**") // 排除删除接口
            .build();
}

如图显示：