如何使用 swagger 3.x 从源注释生成 OAS yaml 文件？

Question

我花了几个小时在 Java 中搜索如何使用 swagger codegen 生成 OAS 规范 yaml 文件，但我放弃了。我想在 Java 源中提供所有 API 规范数据作为代码注释。最好通过 maven 公开它。

AFAIK 我应该使用 swagger-codegen-maven-plugin，但我无法让它扫描源代码以生成 OAS yaml 或 JSON 文件。

我将不胜感激 pom.xml 具有有效代码生成插件配置的片段。

也许我应该回到之前的 Swagger，因为在 2.x 中直接处理了这个用例。现在我对 3.x 方法感到沮丧。

Answer 1

Swagger Codegen 从 OpenAPI 文件生成代码。反其道而行之——从 Java 代码注释生成一个 OpenAPI 文件——你需要 Swagger Core e.g. its Maven plugin, swagger-maven-plugin.

将以下依赖项添加到您的 pom.xml：

<dependencies>
    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-jaxrs2</artifactId>
        <version>2.0.9</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>

然后在您的构建中使用它；示例配置：

   <plugins>
       <plugin>
           <groupId>io.swagger.core.v3</groupId>
           <artifactId>swagger-maven-plugin</artifactId>
           <version>2.0.9</version>
           <configuration>
               <outputFileName>openapi</outputFileName>
               <outputPath>${project.build.directory}/generatedtest</outputPath>
               <configurationFilePath>${project.basedir}/src/main/resources/configurationFile.yaml</configurationFilePath>
           </configuration>
           <executions>
               <execution>
                   <phase>compile</phase>
                   <goals>
                       <goal>resolve</goal>
                   </goals>
               </execution>
           </executions>
       </plugin>
   </plugins>

如何使用 swagger 3.x 从源注释生成 OAS yaml 文件？

How to generate OAS yaml file from sources annotations using swagger 3.x?

swagger

openapi

swagger-codegen

swagger-3.0

swagger-codegen-maven-plugin