如何生成 JSON 或 YAML 格式的 Swagger v3 文档？

Question

我正在使用 Swagger v3 注释来记录我的控制器路由，例如：

@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!";
    }
}

在我的 pom 中，我使用以下插件设置：

            <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>

如果我调用

mvn integration-test

，我会收到以下错误：

[错误]无法在项目 swagger-spring 上执行目标 io.openapitools.swagger:swagger-maven-plugin:2.1.6:generate (generate-openapi): 执行目标 io.openapitools.swagger:swagger- 的generate-openapi maven-plugin:2.1.6:生成失败：扫描仪子类型扫描仪未配置 -> [帮助 1]

我想，我错过了一些配置设置。但哪一个呢？我在开发者网站上找不到任何提示。

更新：

发现可能的错误：https://github.com/openapi-tools/swagger-maven-plugin/issues/96

Answer 1

这是2.1.6版本中的一个错误，我回到2.1.5版本并且可以工作。