非Spring Boot项目用swagger-maven-plugin生成OpenAPI3.0异常咨询

算力阿峰

2026-8-28

问题场景

需要基于非Spring Boot的普通Spring应用源码，通过Maven插件在编译阶段生成OpenAPI 3.0规范的接口定义。
项目Controller类已经使用io.swagger.v3.oas.annotations包下的注解完成标注，示例代码如下：

package com.acme.rest;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;

@Tag(name = "Dummy Controller", description = "Dummy controller.")
@RestController
@RequestMapping("/api/v1/dummy")
public class DummyController {

    @Operation(summary = "dummy(). Does litrally nothing.")
    @RequestMapping(value = "/", method = RequestMethod.GET)
    public String doStuff() {
        return "dummy";
    }
}

使用官方swagger-maven-plugin做如下配置后，执行mvn clean compile仅生成了只包含OpenAPI版本号的空定义文件：

<plugin>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>2.2.0</version>
    <configuration>
        <outputPath>${project.build.directory}/swagger-def</outputPath>
        <resourcePackages>com.acme</resourcePackages>
        <prettyPrint>true</prettyPrint>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>resolve</goal>
            </goals>
        </execution>
    </executions>
</plugin>

生成的空文件内容如下：

{
  "openapi" : "3.0.1"
}

排查发现，该插件默认没有提供io.swagger.v3.oas.integration.api.OpenApiReader和io.swagger.v3.oas.integration.api.OpenApiScanner的实现类来扫描、解析相关注解，必须自定义这两个接口的实现类，再在插件中配置scannerClass、readerClass参数指定自定义实现，才能正常生成接口定义：

<scannerClass>com.acme.util.SwaggerOpenApiScanner</scannerClass>
<readerClass>com.acme.util.SwaggerOpenApiReader</readerClass>

核心疑问：

注解与插件同属io.swagger.core.v3官方分组，为什么开箱即用状态下插件无法解析Swagger注解？
是否遗漏了必要配置？
有哪些可实现该需求的替代Maven插件？

原因说明

官方swagger-maven-plugin本身采用框架无关设计，核心只提供OpenAPI规范对象的序列化、输出基础能力，没有绑定任何特定Web框架的类扫描、注解解析逻辑。

插件默认的内置扫描、读取实现仅能识别swagger-core原生标记的资源，无法识别Spring的@RestController、@RequestMapping等Spring Web专属注解，也不会自动将Spring MVC的接口映射规则转换为OpenAPI标准的路径、参数定义，因此只会输出最基础的版本号信息。
不存在遗漏的核心配置项。swagger官方核心包刻意和具体Web框架解耦，避免给JAX-RS、Servlet等非Spring用户引入不必要的传递依赖，Spring生态的适配逻辑没有放在核心插件包中。若要继续使用该官方插件，除了自定义实现类外，也可以将io.swagger.core.v3:swagger-springweb适配包加入插件的运行时依赖，即可直接使用内置的Spring适配扫描、读取实现，无需自行编写实现类。

替代Maven插件推荐

springdoc-openapi-maven-plugin：内置Spring MVC全版本的注解解析逻辑，原生支持所有io.swagger.v3.oas.annotations包下的注解，不需要自定义Scanner、Reader实现，普通非Spring Boot的Spring MVC项目只要引入对应核心依赖，配置好扫描包路径、输出路径即可在编译期生成标准OpenAPI 3.0定义，配置成本极低，是当前Spring生态下最常用的方案。
smallrye-openapi-maven-plugin：Eclipse基金会旗下的OpenAPI实现插件，内置Spring MVC、JAX-RS等多框架的扫描适配能力，不需要额外编写自定义逻辑，编译期直接扫描源码注解生成规范文件，对非Spring Boot项目兼容性好，支持OpenAPI 3.0、3.1全版本规范。
openapi-generator-maven-plugin：除了根据OpenAPI定义生成接口、客户端代码的能力外，也支持从源码扫描生成OpenAPI规范，搭配Spring适配模块可直接识别Spring MVC Controller与swagger v3注解，生成的规范兼容性强，支持自定义规则扩展。

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