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