openapi-generator plugin

Giriş

Open API içeren yaml dosyasından kod üretir. Yaml dosyasını Swagger Editor ile düzenleriz.

Kod üretmek için şöyle yaparız. 

mvn clean compile

generatorName Alanı

Spring için kod üreteceksek spring değeri verilir.

Örnek

Şöyle yaparız

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>5.1.0</version>
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
      <id>buildApi</id>
      <configuration>

        <!-- specify the location of specification file here -->
        <inputSpec>${basedir}/src/main/resources/open-api.yaml</inputSpec>
                
        <generatorName>spring</generatorName>
        <generateApis>true</generateApis>
        <generateModels>true</generateModels>

        <configOptions>
          <generateSupportingFiles>true</generateSupportingFiles>
          <library>spring-boot</library>
          <interfaceOnly>true</interfaceOnly>
          <useBeanValidation>true</useBeanValidation>
          <sourceFolder>/src/main/java</sourceFolder>
          <implFolder>/src/main/java</implFolder>
          <serializableModel>true</serializableModel>
          <java8>true</java8>
        </configOptions>
      </configuration>
    </execution>
  </executions>
</plugin>

Örnek open-api.yaml dosyası şöyle

openapi: 3.0.3 # version of the specification
info:
  version: '1'
  title: Open API Generator Spring Boot Example

servers:
  - url: http://localhost:8080

paths:
  /parents:
    get:
      summary: return parents information
      operationId: getParents
      responses:
        200:
          description: General parents information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParentResponse'

components:
  schemas:
    ParentResponse:
      discriminator:
        propertyName: ParentResponseType
        mapping:
          Parent: '#/components/schemas/Parent'
      type: object
      properties:
        status:
          type: string
        errorMessage:
          type: string
      description: Response of the parent.

    Parent:
      allOf:
        - $ref: '#/components/schemas/ParentResponse'
        - type: object
          properties:
            parentId:
              type: integer
              description: The ID of the parent
              format: int64
            parentName:
              type: string
              example: 'Stephen'

Üretilen kod şöyle

org.openapitools.api
 ApiUtil
  ParentsApi
org.openapitools.model
  Parent
  ParentAllOf
  ParentResponse

inputSpec Alanı

yaml dosyasının yerini belirtir

Örnek

Şöyle yaparız

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>6.1.0</version>
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
      <configuration>
        <inputSpec>
          ${project.basedir}/src/main/resources/employee.yaml
        </inputSpec>
        <generatorName>spring</generatorName>
        <apiPackage>org.SwaggerCodeGenExample.api</apiPackage>
        <modelPackage>org.SwaggerCodeGenExample.model</modelPackage>
        <configOptions>
          <interfaceOnly>true</interfaceOnly>
        </configOptions>
      </configuration>
    </execution>
  </executions>
</plugin>

üretilen kodun derlenmesi için şu dependency listesi gerekir

<dependencies>
  <dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>2.2.2</version>
  </dependency>
  <dependency>
    <groupId>org.openapitools</groupId>
    <artifactId>jackson-databind-nullable</artifactId>
    <version>0.2.2</version>
  </dependency>
  <dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
    <version>2.0.1.Final</version>
  </dependency>
</dependencies>

Üretilen kod /target/generated-sources/openapi dizinindedir. Kod sadece interface'lerden ibarettir. Daha sonra kendi sınıfımızı üretilen arayüzden kalıtırız. Şöyle yaparız

@RestController
public class EmployeeController implements EmployeeApi {

  @Override
  public ResponseEntity<String> addEmployee(@Valid Employee employee) {
    ...
  }

  @Override
  public ResponseEntity<List<Employee>> getEmployees() {
    ...
  }
}