Как сгенерировать файл OAS yaml из аннотаций источников с помощью Swagger 3.x?

Question

Я потратил часы на поиски того, как сгенерировать yaml-файл спецификации OAS с использованием кодогенератора swagger на Java, и я сдаюсь. Я хотел бы предоставить все данные спецификации API в исходном коде Java в виде аннотаций кода. Было бы здорово выставить его через maven.

Насколько мне известно, я должен использовать swagger-codegen-maven-plugin, но мне не удалось заставить его сканировать исходный код для создания файла OAS yaml или JSON.

Я был бы признателен за фрагмент pom.xml с действующей конфигурацией плагина codegen.

Возможно, мне стоит вернуться к предыдущему Swagger, поскольку этот вариант использования был реализован прямо в 2.x. Теперь я разочарован подходом 3.x.

Answer 1

Swagger Codegen генерирует код из файла OpenAPI. Чтобы сделать наоборот - сгенерировать файл OpenAPI из аннотаций кода Java - вам понадобится 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>