Spring Boot 3.x集成springdoc-openapi实践指南

1. 项目概述

最近在升级Spring Boot 3.x项目时，发现原先使用的springfox-swagger已经不再兼容新版本。经过调研，最终选择了springdoc-openapi作为替代方案。它不仅完美支持Spring Boot 3.x，还内置了Swagger UI和webmvc-api功能，使用起来非常方便。下面就来详细分享我的集成过程和踩坑经验。

2. 为什么选择springdoc-openapi

2.1 springfox的局限性

在Spring Boot 2.x时代，springfox是Swagger集成的首选方案。但随着Spring Boot 3.x的发布，springfox由于以下原因不再适用：

• 对Jakarta EE 9+的支持不足
• 项目维护停滞
• 与Spring WebFlux兼容性问题

2.2 springdoc的优势

相比之下，springdoc-openapi具有明显优势：

1. 原生支持Spring Boot 3.x和Jakarta EE 9+
2. 活跃的社区维护
3. 更简洁的配置方式
4. 内置Swagger UI和OpenAPI 3.0支持
5. 完美兼容WebMVC和WebFlux

3. 集成步骤详解

3.1 基础依赖配置

首先在pom.xml中添加核心依赖：

xml复制<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
</dependency>

如果是WebFlux项目，则使用：

xml复制<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.1.0</version>
</dependency>

3.2 基础配置

在application.yml中添加基本配置：

yaml复制springdoc:
  swagger-ui:
    path: /swagger-ui.html
    operationsSorter: alpha
    tagsSorter: alpha
  api-docs:
    path: /v3/api-docs
  default-consumes-media-type: application/json
  default-produces-media-type: application/json

3.3 接口文档配置

可以通过@OpenAPIDefinition注解自定义文档信息：

java复制@OpenAPIDefinition(
    info = @Info(
        title = "订单服务API",
        version = "1.0",
        description = "订单服务接口文档",
        contact = @Contact(name = "技术支持", email = "support@example.com")
    ),
    servers = @Server(url = "http://localhost:8080", description = "本地环境")
)
public class OpenApiConfig {
}

4. 高级配置技巧

4.1 分组配置

对于大型项目，可以使用分组功能：

java复制@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("public-apis")
            .pathsToMatch("/public/**")
            .build();
}

@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
            .group("admin-apis")
            .pathsToMatch("/admin/**")
            .addOpenApiMethodFilter(method -> method.isAnnotationPresent(AdminOnly.class))
            .build();
}

4.2 安全配置

集成Spring Security时，需要配置白名单：

java复制@Configuration
public class SecurityConfig {
    
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(
                    "/swagger-ui/**",
                    "/v3/api-docs/**",
                    "/swagger-ui.html"
                ).permitAll()
                .anyRequest().authenticated()
            );
        return http.build();
    }
}

4.3 自定义UI配置

可以修改Swagger UI的默认样式：

yaml复制springdoc:
  swagger-ui:
    disable-swagger-default-url: true
    urls[0]:
      url: /v3/api-docs/public-apis
      name: 公共API
    urls[1]:
      url: /v3/api-docs/admin-apis
      name: 管理API
    layout: StandaloneLayout
    persistAuthorization: true

5. 接口注解详解

5.1 基础注解

java复制@Operation(summary = "创建订单", description = "创建新的订单")
@PostMapping("/orders")
public ResponseEntity<Order> createOrder(
    @Parameter(description = "订单信息", required = true) 
    @RequestBody OrderRequest request) {
    // 实现逻辑
}

5.2 响应注解

java复制@Operation(summary = "获取订单详情")
@ApiResponses({
    @ApiResponse(responseCode = "200", description = "成功获取订单",
                 content = @Content(schema = @Schema(implementation = Order.class))),
    @ApiResponse(responseCode = "404", description = "订单不存在")
})
@GetMapping("/orders/{id}")
public ResponseEntity<Order> getOrder(
    @Parameter(description = "订单ID") @PathVariable Long id) {
    // 实现逻辑
}

5.3 枚举处理

java复制@Schema(description = "订单状态", allowableValues = {"CREATED", "PAID", "SHIPPED", "COMPLETED"})
public enum OrderStatus {
    CREATED, PAID, SHIPPED, COMPLETED
}

6. 常见问题解决

6.1 接口文档不显示

可能原因及解决方案：

1. 路径冲突：检查是否有其他拦截器拦截了/swagger-ui.html
2. 依赖冲突：执行mvn dependency:tree检查是否有冲突
3. 版本不匹配：确保springdoc版本与Spring Boot版本兼容

6.2 参数类型识别错误

解决方法：

1. 显式使用@Parameter注解指定类型
2. 对于复杂对象，使用@Schema注解定义结构
3. 确保Jackson配置正确

6.3 性能问题

优化建议：

1. 生产环境禁用Swagger UI：

   yaml复制springdoc:
     swagger-ui:
       enabled: false
   

2. 使用分组减少扫描范围
3. 设置缓存：

   yaml复制springdoc:
     cache:
       disabled: false
   

7. 生产环境最佳实践

7.1 安全建议

1. 生产环境建议：

   • 限制访问IP
   • 添加认证
   • 使用HTTPS

2. 示例配置：

java复制@Profile("!prod")
@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI springShopOpenAPI() {
        // 开发环境才启用完整文档
    }
}

7.2 文档导出

可以通过以下方式导出文档：

1. 直接访问/v3/api-docs端点获取JSON
2. 使用swagger-codegen生成客户端
3. 集成Redoc等替代UI

7.3 版本管理

建议将API文档与代码版本保持一致：

1. 使用Git版本控制
2. 集成CI/CD自动生成文档
3. 存档历史版本文档

8. 扩展功能

8.1 多语言支持

java复制@Operation(summary = "#{swagger.order.create.summary}")
@PostMapping("/orders")
public ResponseEntity<Order> createOrder(
    @Parameter(description = "#{swagger.order.request.desc}") 
    @RequestBody OrderRequest request) {
    // 实现逻辑
}

8.2 自定义UI皮肤

1. 覆盖默认静态资源
2. 使用自定义主题：

yaml复制springdoc:
  swagger-ui:
    config-url: /my-config.yaml

8.3 集成测试

可以结合Spring REST Docs：

java复制@AutoConfigureRestDocs
@AutoConfigureMockMvc
@SpringBootTest
class OrderApiDocumentation {

    @Test
    void createOrderExample() throws Exception {
        mockMvc.perform(post("/orders")
            .contentType(MediaType.APPLICATION_JSON)
            .content("{\"productId\":1,\"quantity\":2}"))
            .andExpect(status().isOk())
            .andDo(document("create-order"));
    }
}

在实际项目中，我发现springdoc-openapi的响应式支持特别出色，对于使用WebFlux的项目，文档生成和UI展示都能完美工作。另外，它的扩展性也很强，我们团队基于它开发了内部文档管理系统，自动同步所有微服务的API文档。