springdoc-openapi-ui的Swagger UI无法识别openapi-generator生成的@Controller类接口

1. 解决生成控制器默认带@Controller注解无法被扫描的问题 #

你不需要额外自定义控制器实现SvcApi接口，直接调整openapi-generator-maven-plugin的生成配置即可，让生成器自动给控制器添加@RestController注解：
在你的pom.xml中找到openapi-generator-maven-plugin的配置，添加useRestController=true配置项：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>你的插件版本</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>你的openapi yaml文件路径</inputSpec>
                <generatorName>spring</generatorName>
                <configOptions>
                    <!-- 核心配置：生成的控制器自动添加@RestController注解 -->
                    <useRestController>true</useRestController>
                    <interfaceOnly>false</interfaceOnly>
                    <!-- 确保basePath和你yaml中的配置一致 -->
                    <basePath>/books/api/v1</basePath>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

重新执行mvn clean generate-sources后，生成的控制器会自动携带@RestController注解，SpringDoc会自动扫描到接口定义，不会再出现"No operations defined in spec!"的提示。

2. 解决Swagger UI "Try it out"请求不带路径前缀的问题 #

两种方案可选，推荐第一种：

方案1：配置自定义OpenAPI Bean注入全局服务路径 #

新增Spring配置类，手动注入OpenAPI实例，指定服务前缀，这样Swagger UI会自动拼接前缀生成请求路径：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.servers.Server;
import java.util.List;

@Configuration
public class SpringDocConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                // 配置和你yaml中一致的服务前缀
                .servers(List.of(new Server().url("/books/api/v1")));
    }
}

方案2：直接指定Swagger UI读取原始OpenAPI YAML #

把你的openapi-definition.yaml放到项目src/main/resources/static目录下，然后在application.yml中添加如下配置：

springdoc:
  swagger-ui:
    # 直接读取你原始的yaml文件，接口定义和路径完全和你定义的一致
    url: /openapi-definition.yaml

3. 注意事项 #

• 删掉你自定义的AddonController，避免同时存在两个SvcApi实现类，导致出现带前缀和不带前缀的两份重复接口
• 如果还是扫描不到生成的控制器，可以在application.yml中添加扫描包配置：

springdoc:
  packages-to-scan: 你的生成控制器所在的完整包名，比如com.xxx.generated.controller

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