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

最新推荐文章于 2025-04-03 17:59:53 发布

潘多编程

最新推荐文章于 2025-04-03 17:59:53 发布

阅读量247

点赞数 4

本文链接：https://blog.youkuaiyun.com/h356363/article/details/146966931

版权

一、环境准备与技术选型

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", "tech@example.com");
    }

    @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"
)

四、文档访问与调试

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

五、常见问题排查

5.1 版本兼容性问题

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

5.2 文档未生成检查项

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

六、最佳实践建议

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

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

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