使用 maven 插件在編譯時從 Spring 應用程序源生成 OpenAPI 3.0 json/yaml

Question

我想在編譯時使用 maven 插件從現有的 Spring（注意：NOT Boot）應用程序源生成 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

<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版本我什么都沒有。

mvn clean compile ，產生：

{
  "openapi" : "3.0.1"
}

---

I dug a bit through the implementation and it seems like there is no io.swagger.v3.oas.integration.api.OpenApiReader and/or io.swagger.v3.oas.integration.api.OpenApiScanner implementation to actually pick up the relevant注釋並解析它們。 我從以下事實得出這個結論：如果我按照文檔中的建議添加它們的自定義實現，我可以生成源代碼。

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

I just dont understand why out of the box SWAGGER plugin does not parse SWAGGER annotations despite both of them are from the very same group io.swagger.core.v3 ?

我錯過了什么？ 你能推薦一些替代插件來完成這項工作嗎？

Answer 1

我在我的項目中使用 Swagger v3 注釋，我遇到了同樣的問題。

我發現springdoc-openapi-maven-plugin使用 Maven 中的springdoc-openapi-ui依賴項與生成的 Swagger 文檔一起工作。

這是我在 Maven 中的配置：

    <profiles>
        <profile>
            <id>apidoc</id>
            <dependencies>
                <dependency>
                    <groupId>org.springdoc</groupId>
                    <artifactId>springdoc-openapi-ui</artifactId>
                    <version>${springdoc-openapi-ui.version}</version>
                </dependency>
            </dependencies>

            <build>
                <plugins>

                    <plugin>
                        <groupId>org.springframework.boot</groupId>
                        <artifactId>spring-boot-maven-plugin</artifactId>
                        <configuration>
                            <excludes>
                                <exclude>
                                    <groupId>org.projectlombok</groupId>
                                    <artifactId>lombok</artifactId>
                                </exclude>
                            </excludes>
                            <jvmArguments>-Dspring.application.admin.enabled=true</jvmArguments>
                        </configuration>
                        <executions>
                            <execution>
                                <id>pre-integration-test</id>
                                <goals>
                                    <goal>start</goal>
                                </goals>
                            </execution>
                            <execution>
                                <id>post-integration-test</id>
                                <goals>
                                    <goal>stop</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>

                    <plugin>
                        <groupId>org.springdoc</groupId>
                        <artifactId>springdoc-openapi-maven-plugin</artifactId>
                        <version>1.4</version>
                        <executions>
                            <execution>
                                <id>integration-test</id>
                                <goals>
                                    <goal>generate</goal>
                                </goals>
                            </execution>
                        </executions>
                        <configuration>
                            <apiDocsUrl>http://localhost:8090/v3/api-docs.yaml</apiDocsUrl>
                            <outputFileName>openapi.yaml</outputFileName>
                            <outputDir>${project.basedir}/src/main/doc/swagger</outputDir>
                            <skip>false</skip>
                        </configuration>
                    </plugin>
                </plugins>
            </build>

        </profile>

關於這個插件的更多信息在這里：

• https://springdoc.org/plugins.html
• https://github.com/springdoc/springdoc-openapi-maven-plugin