Spring Boot 3.0整合SwaggerUI：真香警告！开发效率提升100%的API文档神器

原创已于 2025-02-24 13:27:38 修改 · 1.3k 阅读 ·

本内容遵循CC 4.0 BY-SA版权协议

月落星还在

关注

标签

#spring boot #后端 #java

分类后端开发

于 2025-02-24 12:04:44 首次发布

一、SwaggerUI是什么？为什么开发者都说"真香"？

SwaggerUI是一款基于OpenAPI规范的API可视化调试工具，它通过自动扫描代码生成交互式文档，让开发者可以：

实时查看所有API端点及参数说明
直接在浏览器发起API请求测试
自动生成多种语言客户端代码
支持OAuth2/JWT等复杂鉴权配置

2023年最新技术栈适配：Spring Boot 3.0全面拥抱Jakarta EE，而springdoc-openapi 2.x完美适配Spring Boot 3.x，解决了传统springfox不兼容的问题。

二、Spring Boot 3.0极简配置指南

1. 添加依赖（关键版本匹配！）

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version> <!-- 专门为Spring Boot 3.x优化 -->
</dependency>

2. 基础配置类

@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").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("项目Wiki")
                        .url("https://github.com/your-repo"));
    }
}

3. application.yml配置（按需开启安全）

springdoc:
  swagger-ui:
    path: /swagger-ui.html # UI访问路径
    operationsSorter: method # 按HTTP方法排序
    tagsSorter: alpha # 标签字母排序
  api-docs:
    path: /v3/api-docs # 文档JSON路径
  default-consumes-media-type: application/json
  default-produces-media-type: application/json

三、开发实战：从零到完美文档

1. 控制器注解示例

@RestController
@Tag(name = "用户模块", description = "用户注册登录及信息管理")
@RequestMapping("/api/users")
public class UserController {

    @Operation(summary = "用户登录", description = "通过手机号+密码获取Token")
    @ApiResponses({
        @ApiResponse(responseCode = "200", description = "登录成功"),
        @ApiResponse(responseCode = "401", description = "认证失败")
    })
    @PostMapping("/login")
    public ResponseEntity<TokenDTO> login(
            @Parameter(description = "登录请求体", required = true) 
            @RequestBody LoginRequest request) {
        // 业务逻辑
    }
}

2. DTO字段说明

public class UserDTO {
    
    @Schema(description = "用户ID", example = "123")
    private Long id;

    @Schema(description = "用户名", minLength = 6, maxLength = 20)
    @NotBlank
    private String username;
}

四、SwaggerUI的六大杀手级功能

1. 实时API调试台

支持文件上传测试
自动携带Authorization头
响应结果直接格式化展示

2.智能文档生成

// 通过分组实现模块化管理
@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("users")
            .pathsToMatch("/api/users/**")
            .build();
}

3.安全集成方案

// JWT配置示例
OpenAPI springShopOpenAPI() {
    return new OpenAPI()
            .components(new Components()
                    .addSecuritySchemes("bearerAuth", 
                        new SecurityScheme()
                            .type(SecurityScheme.Type.HTTP)
                            .scheme("bearer")
                            .bearerFormat("JWT")))
            .addSecurityItem(new SecurityRequirement().addList("bearerAuth"));
}

4.多环境配置策略

# 生产环境禁用Swagger
spring:
  profiles: prod
springdoc:
  swagger-ui:
    enabled: false
  api-docs:
    enabled: false

5.文档导出与分享

访问 /v3/api-docs.yaml 获取YAML格式
使用 http://localhost:8080/v3/api-docs
导出JSON 支持导入Postman等工具

6.深度定制能力

springdoc:
  swagger-ui:
    persistAuthorization: true # 保持授权状态
    filter: true # 启用搜索过滤
    syntaxHighlight:
      activated: true # 语法高亮
      theme: obsidian # 暗黑主题

五、常见问题排雷指南

1.404问题排查：

检查@EnableWebMvc是否冲突
确认路径未被Security拦截
验证依赖版本是否匹配

2.枚举显示优化：

@Schema(type = "string", allowableValues = {"AUDIT", "PUBLISHED"})
private ArticleStatus status;

3.泛型处理技巧：

@ArraySchema(schema = @Schema(implementation = UserDTO.class))
private List<?> data;

六、为什么选择springdoc-openapi？

相较于传统的springfox：

✅ 原生支持Spring Boot 3.0
✅ 更活跃的社区维护
✅ 响应式编程支持
✅ 更简洁的配置方式
✅ 更好的性能表现

七、总结

通过本文的配置实践，我们已经实现了：

自动化API文档生成
零配置的接口测试平台
完善的权限管理集成
多环境适配方案

升级建议：随着Spring Boot 3.x的普及，建议所有新项目直接采用springdoc-openapi方案。对于存量项目，迁移成本极低，只需替换依赖和少量注解调整即可。

更多高级用法参考官方文档：https://springdoc.org/

彩蛋：尝试在SwaggerUI的filter栏输入curl，即可获取当前请求的cURL命令！🎉

【作者注】本文基于Spring Boot 3.0.5 + springdoc-openapi 2.6.0编写，实测可用。如果遇到问题，欢迎在评论区交流讨论~