Spring Boot微服务多控制器Swagger配置异常求助

Let me walk you through the most common fixes for this issue— I’ve hit this exact problem a few times when setting up Swagger with multiple Spring Boot controllers. Here’s what to check:

1. Fix Your Docket Configuration (Most Likely Culprit) #

Looking at your partial SwaggerConfig, it seems you might not have a complete Docket bean defined. Swagger relies on this bean to specify which APIs to scan and display. If your current setup only targets the first controller’s package, the second one won’t show up.

Update your SwaggerConfig to include a properly configured Docket:

@EnableSwagger2
@PropertySource("classpath:swagger.properties")
@ComponentScan(basePackageClasses = { WebController.class, TestController.class})
@Configuration
public class SwaggerConfig {
    private static final String SWAGGER_API_VERSION = "1.0";
    private static final String LICENSE_TEXT = "License";
    private static final String title = "Your API Title";
    private static final String description = "Your API Description";

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // Option 1: Scan all controllers with @RestController annotation
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                // Option 2: Scan a base package containing all your controllers
                // .apis(RequestHandlerSelectors.basePackage("com.yourproject.controllers"))
                // Include all paths (adjust if you need to filter)
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .version(SWAGGER_API_VERSION)
                .license(LICENSE_TEXT)
                .build();
    }
}

2. Verify Your Second Controller’s Annotations #

Double-check that your TestController has the correct Spring and Swagger annotations:

• Make sure it’s annotated with @RestController (standard for REST APIs; use @Controller only if returning views).
• Ensure every endpoint method has HTTP mapping annotations like @GetMapping, @PostMapping, etc.— Swagger won’t list methods without these.
• Avoid @ApiIgnore on the controller or its methods (this tells Swagger to skip the component entirely).

Example of a valid controller:

@RestController
@RequestMapping("/test-api")
// Optional: Add @Api to give Swagger more context
@Api(value = "Test Controller", description = "Endpoints for testing purposes")
public class TestController {

    @GetMapping("/greet")
    @ApiOperation(value = "Get a greeting message", response = String.class)
    public String getGreeting() {
        return "Hello from Test Controller!";
    }
}

3. Check Component Scan Scope Conflicts #

Even though you’ve added @ComponentScan to SwaggerConfig, if your Spring Boot main application class has a @ComponentScan annotation with a narrower scope, it might override this setting. For example, if your main class only scans com.yourproject.web (where WebController lives) but TestController is in com.yourproject.test, it won’t be picked up.

Make sure your main application class’s @ComponentScan includes all packages containing your controllers, or remove it entirely (Spring Boot defaults to scanning the package of the main class and its subpackages).

4. Rule Out Version Compatibility Issues #

If you’re using Spring Boot 2.x, ensure you’re using a compatible Swagger 2 version (I recommend 2.9.2 or later). Mismatched versions can cause unexpected scanning behavior. Here’s a typical Maven dependency snippet:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Note: If you’re on Spring Boot 3.x, @EnableSwagger2 is deprecated— you’ll need to switch to SpringDoc OpenAPI instead.

5. Clear Cache and Restart Your App #

Sometimes, stale build cache can prevent Swagger UI from updating. Stop your Spring Boot app, clear build artifacts (like the target folder for Maven), and restart it. Then refresh the swagger-ui.html page to see if the second controller appears.

内容的提问来源于stack exchange，提问作者Mr.DevEng