Spring Boot 3集成OpenAPI3（Swagger）生成未知接口文档问题求助

可能原因 #

• Spring Boot自动配置端点被扫描：Spring Boot自带的Actuator端点、错误处理端点（如/error）或其他自动配置的控制器，会被springdoc默认扫描并生成文档。
• 依赖传递引入第三方控制器：项目依赖（如第三方starter、工具库）中包含了@RestController注解的类，这些类被Spring上下文加载后，会被springdoc识别并加入文档。
• 组件扫描范围过广：如果主应用类未指定精确的扫描包，Spring会默认扫描所有路径下的组件，导致第三方库或自动配置中的控制器被纳入扫描范围。
• RequestMapping通配符不严谨：你的TariffController使用了"*/tariff"这种模糊的路径通配符，可能导致springdoc将其他匹配该模式的未知路径错误关联到控制器，表现为“随机名称”的接口。

解决办法 #

1. 限制springdoc的扫描范围 #

通过GroupedOpenApi指定只扫描自己的控制器包和路径：

@Configuration
@OpenAPIDefinition(
        info = @Info(
                title = "Billing System Api",
                description = "Billing System", version = "1.0.0",
                contact = @Contact(
                        name = "Protchenko Kirill",
                        email = "kirill.protchenko@mail.ru",
                        url = "https://github.com/kirlozavr/BillingSystem"
                )
        )
)
public class OpenApiConfig {
    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("billing-system")
                .packagesToScan("com.yourpackage.controller") // 替换为你的控制器所在包
                .pathsToMatch("/tariff/**") // 只匹配你的业务接口路径
                .build();
    }
}

2. 排除不需要的端点 #

在配置文件中添加springdoc的排除规则，忽略Actuator、错误端点等：

# application.yml
springdoc:
  paths-to-exclude: /actuator/**, /error, /swagger-resources/**

3. 检查并清理依赖 #

用依赖分析工具排查引入额外控制器的依赖：

• Maven执行：mvn dependency:tree
• Gradle执行：./gradlew dependencies
  找到可疑依赖后，通过<exclusions>排除其中的无关组件。

4. 缩小Spring组件扫描范围 #

在主应用类上明确指定扫描包，避免加载无关组件：

@SpringBootApplication(scanBasePackages = "com.yourpackage") // 替换为你的项目根包
public class BillingSystemApplication {
    public static void main(String[] args) {
        SpringApplication.run(BillingSystemApplication.class, args);
    }
}

5. 修正RequestMapping路径 #

将模糊通配符改为精确路径，避免不必要的路径匹配：

@RestController
@RequestMapping("/tariff") // 去掉前面的通配符*
@Tag(name = "Тариф", description = "Контроллер отвечает за crud операции с тарифами")
public class TariffController {
    // ... 原有代码
}

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