Spring Boot 3.0 + JDK 17整合SpringDoc实战指南

一、环境准备与技术选型

1.1 开发环境要求

• JDK 17+
• Maven 3.6+
• IntelliJ IDEA 2023.1+ (或其他支持JDK 17的IDE)

1.2 技术选型说明

• Spring Boot 3.0：基于Jakarta EE 9+规范
• SpringDoc 2.x：支持OpenAPI 3规范的文档工具
• JDK 17：长期支持版本（LTS）

二、实战步骤演示

2.1 初始化项目

通过Spring Initializr创建项目时选择：

• Spring Web
• Lombok（推荐）
• Validation（推荐）

<!-- pom.xml 关键依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
</dependency>

2.2 基础API示例

@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理", description = "用户相关操作接口")
public class UserController {

    @Operation(summary = "获取用户详情", description = "根据ID查询用户详细信息")
    @GetMapping("/{id}")
    public User getUser(@Parameter(description = "用户ID") @PathVariable Long id) {
        return new User(id, "tech_author", "[e-mail]");
    }

    @Operation(summary = "创建用户")
    @PostMapping
    public User createUser(@RequestBody User user) {
        return user;
    }
}

2.3 SpringDoc配置类

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("电商平台API")
                        .description("Spring Boot 3.0实战文档")
                        .version("v1.0.0")
                        .license(new License().name("Apache 2.0")))
                .externalDocs(new ExternalDocumentation()
                        .description("项目Wiki")
                        .url("https://github.com/your-repo"));
    }
}

2.4 常用配置项

# application.properties
springdoc.swagger-ui.path=/api-docs
springdoc.api-docs.path=/v3/api-docs
springdoc.show-actuator=true
springdoc.cache.disabled=true

三、高级配置技巧

3.1 接口分组配置

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

@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
            .group("admin-apis")
            .pathsToMatch("/admin/**")
            .build();
}

3.2 安全集成配置

@SecurityScheme(
  name = "BearerAuth",
  type = SecuritySchemeType.HTTP,
  bearerFormat = "JWT",
  scheme = "bearer"
)

四、文档访问与调试

1. Swagger UI访问地址：http://localhost:8080/api-docs
2. OpenAPI JSON地址：http://localhost:8080/v3/api-docs

五、常见问题排查

5.1 版本兼容性问题

• 确保SpringDoc版本与Spring Boot 3.0兼容
• 使用正确的Jakarta包路径（javax包已废弃）

5.2 文档未生成检查项

1. 检查Controller是否被正确扫描
2. 验证路径匹配规则
3. 查看启动日志是否有异常

六、最佳实践建议

1. 使用DTO作为接口参数和返回值
2. 为每个响应状态添加@ApiResponse
3. 结合Validation注解生成参数约束说明
4. 定期清理废弃接口文档

项目完整配置示例：
GitHub示例仓库

---

注： 本文基于Spring Boot 3.0.6和SpringDoc 2.1.0编写，实际开发时请验证最新版本兼容性。建议结合CI/CD实现文档自动化部署，提升团队协作效率。