如何生成Swagger v3的JSON/YAML文档？Maven插件执行报错求助

问题场景 #

使用Swagger v3注解编写控制器接口文档，配置swagger-maven-plugin执行mvn integration-test生成OpenAPI文档时，抛出扫描器未配置的错误。

代码示例 #

控制器代码 #

@OpenAPIDefinition(info = 
    @Info(title = "swagger-spring", 
          description = "testing swagger in a spring environment", 
          version = "0.1", 
          contact = @Contact(name = "Thilo Schwarz", 
                             email = "osp (at) domain.codes", 
                             url = "https://domain.codes")))
public class Controller {

    @Operation(summary = "Says hello.")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200",
                         description = "Just returns 'hello'.",
                         content = @Content(mediaType = "text/plain",
                                            examples = {@ExampleObject(value = "HELLO!") })) })
    public String hello() {
        return "HELLO!";
    }
}

Maven插件配置 #

<plugin>
    <groupId>io.openapitools.swagger</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>2.1.6</version>
    <configuration>
        <resourcePackages>
            <resourcePackage>codes.thischwa.swagger</resourcePackage>
        </resourcePackages>
        <outputDirectory>${project.build.directory}/</outputDirectory>
        <outputFilename>openapi</outputFilename>
        <outputFormats>JSON,YAML</outputFormats>
        <prettyPrint>true</prettyPrint>
    </configuration>
    <executions>
        <execution>
            <id>generate-openapi</id>
            <phase>integration-test</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <dependencies>
        <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-jaxrs2</artifactId>
            <version>2.2.2</version>
        </dependency>
        <dependency>
            <groupId>javax.ws.rs</groupId>
            <artifactId>javax.ws.rs-api</artifactId>
            <version>2.1</version>
        </dependency>
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <version>3.1.0</version>
        </dependency>
    </dependencies>
</plugin>

错误信息 #

[ERROR] Failed to execute goal io.openapitools.swagger:swagger-maven-plugin:2.1.6:generate (generate-openapi) on project swagger-spring: Execution generate-openapi of goal io.openapitools.swagger:swagger-maven-plugin:2.1.6:generate failed: Scanner SubTypesScanner was not configured -> [Help 1]

解决方案 #

该问题是swagger-maven-plugin 2.1.6版本的已知Bug，可通过以下两种方式解决：

方案一：升级插件版本 #

将插件版本从2.1.6升级到2.1.7及以上，新版本已修复扫描器配置缺失的问题。修改后的插件版本配置如下：

<version>2.1.7</version>

方案二：手动指定扫描器（适用于无法升级版本的场景） #

在插件的<configuration>块中添加扫描器配置项，指定正确的扫描器类：

<configuration>
    <!-- 原有配置保持不变 -->
    <scanner>io.swagger.v3.plugins.scanner.JaxrsOpenApiScanner</scanner>
</configuration>

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