Springfox迁移Springdoc后API文档Tags及操作摘要缺失问题求助

1. 排查依赖配置 #

确保Gradle依赖包含Springdoc核心注解解析组件，仅springdoc-openapi-ui和javadoc可能不够，需补充适配Spring Boot 2.5.x的核心依赖：

implementation 'org.springdoc:springdoc-openapi-ui:1.6.0'
implementation 'org.springdoc:springdoc-openapi-webmvc-core:1.6.0'
implementation 'org.springdoc:springdoc-openapi-javadoc:1.6.0'

同时彻底清理项目中残留的Springfox依赖，避免冲突：

configurations.all {
    exclude group: 'io.springfox', module: 'springfox-swagger2'
    exclude group: 'io.springfox', module: 'springfox-swagger-ui'
}

2. 校验注解使用正确性 #

• 确认控制器类上的@Tag注解是io.swagger.v3.oas.annotations.tags.Tag，别误用Springfox的旧注解（如springfox.documentation.annotations.Api）。
• 接口方法的@Operation注解中，tags属性值必须和类上@Tag的name完全一致，示例：

@Tag(name = "Master", description = "Master service API")
@RestController
@RequestMapping("/master")
public class MasterController {

    @Operation(summary = "获取Master详情", tags = {"Master"})
    @GetMapping("/{id}")
    public ResponseEntity<Master> getMaster(@PathVariable Long id) {
        // 业务逻辑
    }
}

如果@Operation未指定tags，会自动继承类上的@Tag，但如果指定了空数组或错误名称，就会显示null。

3. 检查包扫描配置 #

确保application.properties中使用Springdoc的正确配置项，而非Springfox的旧配置：

# 扫描控制器所在的包，多个包用逗号分隔
springdoc.packages-to-scan=com.yourproject.controller
# 可选：指定要生成文档的接口路径匹配规则
springdoc.paths-to-match=/master/**

4. 修正OpenAPI配置Bean #

如果自定义了OpenAPI配置Bean，不要手动设置空的tags集合，否则会覆盖框架自动收集的tags。正确配置示例：

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Master Service API")
                        .version("1.0")
                        .description("Master服务接口文档"));
        // 避免添加 .tags(new ArrayList<>()) 这类覆盖性代码
    }
}

5. 验证访问路径 #

注意Springdoc的标准API文档路径是/v3/api-docs，而非你提到的v3/apidocs（缺少开头斜杠），路径错误会返回空文档导致tags不显示。同时访问/swagger-ui.html可直观查看页面是否正常渲染tags和摘要。

内容的提问来源于stack exchange，提问作者jslearner07