Swagger2与Springdoc集成与使用详解

Swagger2与Springdoc集成与使用详解

一、技术选型对比

1. Swagger2（基于Springfox）：

   • 支持OpenAPI 2.0规范
   • 注解体系：@Api/@ApiOperation
   • 配置类：Docket
   • 访问路径：/swagger-ui.html

2. Springdoc：

   • 支持OpenAPI 3.0规范
   • 注解体系：@Tag/@Operation
   • 自动配置机制
   • 访问路径：/swagger-ui/index.html

二、集成步骤

1. 添加依赖（替换Springfox）：

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

2. 基础配置类：

@Configuration
@OpenAPIDefinition(
    info = @Info(
        title = "API文档",
        version = "1.0",
        description = "系统接口文档"
    )
)
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .components(new Components())
            .addSecurityItem(new SecurityRequirement().addList("JWT"));
    }
}

3. 接口标注示例：

@Tag(name = "用户模块")
@RestController
@RequestMapping("/users")
public class UserController {

    @Operation(summary = "获取用户详情")
    @GetMapping("/{id}")
    public User getUser(@Parameter(description = "用户ID") @PathVariable Long id) {
        return userService.getById(id);
    }
}

三、配置调优

# 开启文档生成（生产环境建议关闭）
springdoc.api-docs.enabled=true
# 分组配置示例
springdoc.group-configs[0].group=admin
springdoc.group-configs[0].paths-to-match=/admin/**

四、安全集成方案

@Configuration
@SecurityScheme(
    name = "JWT",
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT"
)
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    // 安全配置...
}

五、常见问题排查

1. 依赖冲突：

   • 移除springfox-swagger2和springfox-swagger-ui
   • 检查是否包含springdoc-openapi-webflux-core（WebFlux项目专用）

2. 接口未扫描：

# 指定扫描包路径
springdoc.packagesToScan=com.example.controller

3. 路径匹配问题（Spring Boot 2.6+）：

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        configurer.setPatternParser(PathPatternParser.defaultInstance);
    }
}

六、高级功能扩展

1. 自定义响应模型：

@Schema(description = "标准响应结构")
public class Result<T> {
    @Schema(description = "状态码")
    private Integer code;
    
    @Schema(description = "业务数据")
    private T data;
}

2. 多版本文档管理：

springdoc.version=1.2.0
springdoc.paths-to-match=/v2/**

3. 性能优化建议：

# 关闭未使用的处理器
springdoc.model-converters.enabled=false
springdoc.override-with-generic-response=false

最佳实践提示：建议在application-dev.yml中开启文档功能，在application-prod.yml中通过springdoc.api-docs.enabled=false关闭文档生成。