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

1. Spring Boot 3.x集成springdoc-openapi全攻略

最近在开发自己的后端项目时，发现手动维护接口文档实在太痛苦了。每次接口有变动，都要同步更新文档，稍不注意就会遗漏。于是我开始研究自动化API文档工具，最终选择了springdoc-openapi这个方案。它不仅能自动生成文档，还内置了Swagger UI可视化界面，让前后端协作变得轻松多了。

不过在实际集成过程中，我发现网上很多教程都是针对Spring Boot 2.x的，Spring Boot 3.x的配置有些不同。经过多次尝试和踩坑，终于成功配置好了。下面就把我的完整配置过程分享给大家，包括可能遇到的坑和解决方案。

2. 技术选型与核心组件

2.1 为什么选择springdoc-openapi

在Java生态中，API文档工具主要有Swagger和springdoc-openapi两大选择。经过对比，我选择了后者，主要基于以下几点考虑：

1. 原生支持OpenAPI 3.0：springdoc-openapi基于最新的OpenAPI 3.0规范，比Swagger 2.x功能更强大
2. 完美适配Spring Boot 3.x：专门为Spring Boot 3.x优化，没有兼容性问题
3. 零配置启动：只需添加依赖就能自动生成文档，开发体验极佳
4. 内置Swagger UI：不需要额外配置，开箱即用的可视化界面

2.2 核心组件解析

springdoc-openapi-starter-webmvc-ui这个依赖包包含了三个核心组件：

1. springdoc-openapi-core：负责扫描Spring MVC控制器并生成OpenAPI规范文档
2. springdoc-openapi-webmvc：提供与Spring Web MVC的集成支持
3. swagger-ui：可视化API文档界面，支持在线测试接口

3. 详细配置步骤

3.1 环境准备

我的开发环境：

• JDK 17（Spring Boot 3.x最低要求）
• Spring Boot 3.1.8
• Maven 3.8.1

3.2 添加依赖

在pom.xml中添加以下依赖：

xml复制<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.1.8</version>
    <relativePath/>
</parent>

<dependencies>
    <!-- 其他依赖 -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.5.0</version>
    </dependency>
</dependencies>

提示：建议添加阿里云镜像加速依赖下载，在pom.xml中添加以下配置（与dependencies同级）：

xml复制<repositories>
    <repository>
        <id>alimaven</id>
        <name>aliyun maven</name>
        <url>https://maven.aliyun.com/nexus/content/groups/public/</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

3.3 基础配置

在application.yml中添加springdoc相关配置：

yaml复制server:
  port: 5000

springdoc:
  api-docs:
    enabled: true # 开启OpenApi接口
    path: /v3/api-docs  # 自定义路径，默认为"/v3/api-docs"
  swagger-ui:
    enabled: true # 开启swagger界面
    path: /swagger-ui/index.html # 自定义路径，默认为"/swagger-ui/index.html"

3.4 自定义Swagger配置

创建SwaggerConfig.java配置类：

java复制package com.yourpackage.config;

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("项目API文档")
                        .contact(new Contact().name("开发者").email("dev@example.com"))
                        .description("项目RESTful API文档")
                        .version("v1.0.0")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("项目Wiki")
                        .url("https://yourproject.wiki.github.org/docs"));
    }
}

4. 常见问题与解决方案

4.1 访问Swagger UI出现404

这是最常见的问题，通常有以下几种原因：

1. 拦截器未排除相关路径：
   如果你使用了拦截器，需要确保放行Swagger相关路径：

java复制@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(loginInterceptor)
        .excludePathPatterns("/api/public/**")
        .excludePathPatterns("/swagger-ui/**", "/v3/api-docs/**");
}

注意：路径匹配要使用/**而不是具体路径，因为Swagger UI会加载多个静态资源

2. 静态资源未正确配置：
   如果项目自定义了静态资源处理，需要确保Swagger UI的静态资源能被访问：

java复制@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/")
                .resourceChain(false);
    }
}

4.2 接口文档不完整

如果发现某些接口没有出现在文档中，可以检查以下几点：

1. 控制器未添加注解：
   确保控制器类上有@RestController或@Controller注解

2. 方法未添加HTTP方法注解：
   确保每个接口方法都有@GetMapping、@PostMapping等注解

3. 包扫描问题：
   默认情况下springdoc会扫描所有包，如果使用了自定义配置，确保包含了控制器所在包

java复制@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("public")
            .packagesToScan("com.yourpackage.controller")
            .build();
}

5. 高级配置技巧

5.1 接口分组管理

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

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

@Bean
public GroupedOpenApi userApi() {
    return GroupedOpenApi.builder()
            .group("user")
            .pathsToMatch("/api/user/**")
            .build();
}

5.2 接口详细描述

通过注解可以增强接口文档的描述信息：

java复制@Operation(summary = "创建用户", description = "创建一个新用户")
@ApiResponses(value = {
    @ApiResponse(responseCode = "201", description = "用户创建成功"),
    @ApiResponse(responseCode = "400", description = "无效的输入参数")
})
@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody @Valid User user) {
    // 实现代码
}

5.3 模型定义增强

使用注解增强DTO模型的文档描述：

java复制@Schema(description = "用户信息")
public class User {
    @Schema(description = "用户ID", example = "1001")
    private Long id;
    
    @Schema(description = "用户名", example = "张三", required = true)
    @NotBlank
    private String name;
    
    @Schema(description = "邮箱", example = "user@example.com")
    @Email
    private String email;
}

6. 安全配置

6.1 生产环境禁用Swagger UI

生产环境建议禁用Swagger UI，只保留API文档接口：

yaml复制springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: false

6.2 添加访问权限

如果需要保护Swagger UI，可以添加基础认证：

java复制@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .components(new Components()
                    .addSecuritySchemes("basicScheme", new SecurityScheme()
                            .type(SecurityScheme.Type.HTTP)
                            .scheme("basic")))
            .info(new Info().title("API文档"))
            .addSecurityItem(new SecurityRequirement().addList("basicScheme"));
}

然后在application.yml中配置访问凭证：

yaml复制springdoc:
  swagger-ui:
    enabled: true
    config-url: /v3/api-docs/swagger-config
    oauth:
      client-id: your-client-id
      client-secret: your-client-secret

7. 最佳实践与经验分享

经过这次集成，我总结了以下几点经验：

1. 版本匹配很重要：Spring Boot 3.x必须使用springdoc-openapi 2.x版本，1.x版本不兼容

2. 路径配置要一致：application.yml中的路径、拦截器排除路径和实际访问路径必须保持一致

3. 注解合理使用：不要过度使用注解，保持文档简洁易读，关键接口和复杂参数才需要详细说明

4. 定期更新依赖：springdoc-openapi更新频繁，定期检查新版本可以获取更好的功能和性能

5. 结合代码审查：将API文档检查纳入代码审查流程，确保文档与实现保持一致

在实际项目中，这套配置已经稳定运行了3个月，大大提高了前后端协作效率。特别是当接口变更时，文档能自动更新，再也不用担心文档过期的问题了。