使用Maven插件生成春季应用程序来源的OpenAPI 3.0 JSON/YAML

Question

我想从现有Spring（注意：不是引导）应用程序源在编译时生成OpenAPI 3.0定义。

我已经在控制器类中设置了 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"
}

---

我通过实现挖掘一点，似乎没有 io.swagger.v3.oas.integration.api.openapireader 和/或 io.swagger.v3.oas.integration.api.openapiscanner 实现以实际获取相关的注释并解析它们。我从一个事实中得出结论：如果我按照 docs 我可以生成的来源。

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

我只是不明白为什么启动Swagger插件不会解析摇摇注释，尽管它们俩都来自同一组 io.swagger.core.v3 ？

什么是什么我错过了什么？您可以推荐一些替代插件来完成这项工作吗？

Answer 1

我正在使用项目中的Swagger V3注释，并且正面临同样的问题。

我找到了使用Maven中 springdoc-openapi-ui springdoc-openapi-maven-plugin ，它与生成的摇摇欲坠文档搭配得很好。

这是我在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 < /a>