为何swagger-maven-plugin无法识别我的API操作？Spring Boot配置求助

你遇到的核心问题是注解版本与插件版本不兼容——你用的是OpenAPI 3.0的注解（io.swagger.v3.oas.annotations包），但旧版swagger-maven-plugin仅支持Swagger 2.x的注解（io.swagger.annotations包），因此无法识别你的API操作。下面是具体的排查和解决步骤：

1. 替换为支持OpenAPI 3的插件 #

旧版io.swagger:swagger-maven-plugin不兼容OpenAPI 3注解，需要改用Swagger Core团队维护的专用插件：io.swagger.core.v3:swagger-maven-plugin。

2. 更新pom.xml的插件配置 #

替换原有插件依赖，添加以下配置（建议使用最新稳定版本）：

<build>
    <plugins>
        <plugin>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-maven-plugin</artifactId>
            <version>2.2.20</version> <!-- 可替换为最新版 -->
            <executions>
                <execution>
                    <phase>compile</phase>
                    <goals>
                        <goal>resolve</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <!-- 生成的OpenAPI文件名称 -->
                <outputFileName>openapi</outputFileName>
                <!-- 文件输出路径 -->
                <outputPath>${project.build.directory}</outputPath>
                <!-- 指定扫描控制器的包路径 -->
                <resourcePackages>
                    <package>com.yourproject.api.controller</package>
                </resourcePackages>
                <!-- 配置API基础信息 -->
                <openAPI>
                    <info>
                        <title>Country API</title>
                        <version>1.0.0</version>
                    </info>
                </openAPI>
            </configuration>
        </plugin>
    </plugins>
</build>

3. 同步Swagger Core依赖版本 #

确保你的Swagger核心依赖与插件版本一致，添加以下依赖到pom.xml：

<dependencies>
    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-core</artifactId>
        <version>2.2.20</version>
    </dependency>
    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>2.2.20</version>
    </dependency>
</dependencies>

4. 检查控制器注解的正确性 #

确认你的控制器注解使用规范：

• 确保控制器类正确标记@RestController和@RequestMapping
• 补全代码中未写完的@Operation注解（你代码里的@Op...属于语法不完整）
• 验证控制器所在包在Spring Boot的扫描范围内（比如被@SpringBootApplication的scanBasePackages覆盖）

5. 验证插件执行效果 #

运行Maven命令 mvn compile，插件会在target目录下生成openapi.json或openapi.yaml文件，打开文件即可检查是否包含CountryController的API操作。如果仍有问题，可运行mvn compile -X查看详细日志，排查包扫描或注解解析的错误提示。

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