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

Question

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

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

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

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

Answer 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>