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

【问题标题】：How to generate OAS yaml file from sources annotations using swagger 3.x?如何使用 swagger 3.x 从源注释生成 OAS yaml 文件？
【发布时间】：2019-09-10 19:59:55
【问题描述】：

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

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

我会很感激 pom.xml 的 sn-p 和有效的 codegen 插件配置。

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

【问题讨论】：

标签： swagger openapi swagger-codegen swagger-3.0 swagger-codegen-maven-plugin

【解决方案1】：

Swagger Codegen 从 OpenAPI 文件生成代码。反之亦然——从 Java 代码注释生成 OpenAPI 文件——你需要 Swagger Core 例如它的 Maven 插件，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>

【讨论】：

如何在基于 Gradle 的项目中使用它？