Quarkus - OpenAPI Generator - Server with OpenAPITools

This documentation helps you to use Quarkus OpenAPI Generator Server with the OpenAPITools code generator. To see how to use with OpenAPITools, please see the Apicurio documentation.

Add the following dependency to your project’s pom.xml file:

<dependency>
  <groupId>io.quarkiverse.openapi.generator</groupId>
  <artifactId>quarkus-openapi-generator-server</artifactId>
  <version>3.0.0-SNAPSHOT</version>
</dependency>

Note that since this extension has not been yet released, you’ll need a local build of the dependency.

You will also need to add or update the quarkus-maven-plugin configuration with the following:

You probably already have this configuration if you created your application with Code Quarkus. That said, double-check your configuration not to add another plugin entry. 
<plugin>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-maven-plugin</artifactId>
  <extensions>true</extensions>
  <executions>
    <execution>
      <goals>
        <goal>build</goal>
        <goal>generate-code</goal>
        <goal>generate-code-tests</goal>
      </goals>
    </execution>
  </executions>
</plugin>

To use the OpenAPITools code generator, you need to configure your application.properties as follow:

quarkus.openapi.generator.server.use=openapitools

Now, create the directory openapi under your src/main/resources path and add the OpenAPI spec files there. We support JSON, YAML and YML extensions. You have to define the specification used for code generation with the following property:

quarkus.openapi.generator.server.spec=petstore-openapi.json

You can see the petstore-openapi.json file through this link.

If you want to change the directory where OpenAPI files must be found, use the property quarkus.openapi.server.input-base-dir.

It is relative to the project base directory. For example, if you have a project called MyJavaProject and decide to place them in MyJavaProject/openapi-definitions, use the following property:

 
quarkus.openapi.generator.server.input-base-dir=openapi-definitions

If a base package name is not provided, it will be used the default org.acme. You can customize it with the following property:

quarkus.openapi.generator.server.base-package=io.petstore

By default, the extension generates non-reactive code. If you would like to change it, you can do it as follows:

quarkus.openapi.generator.server.use-reactive=true

Run mvn compile to generate your classes in target/generated-sources/quarkus-openapi-generator-server path:

- io.petstore
  - model
    - Address.java
    - ApiResponse.java
    - Category.java
    - Customer.java
    - Order.java
    - Pet.java
    - Tag.java
    - User.java
  - resources
    - PetResource.java
    - StoreResource.java
    - UserResource.java

You can reference the generated code in your project, for example:

public class DefaultPetResource implements PetResource {

    private static final Map<Long, Pet> PET_STORE_DB = new ConcurrentHashMap<>();
    Random random = new Random();

    @Override
    public Uni<Pet> addPet(Pet pet) {
        long l = random.nextLong();
        Pet createdPet = new Pet()
                .id(l)
                .name("Melina")
                .category(new Category().id(l).name("Dog"))
                .addTagsItem(new Tag().id(l).name("SMALL"))
                .photoUrls(List.of("https://picsum.photos/id/237/200/300"))
                .status(Pet.StatusEnum.AVAILABLE);

        return Uni.createFrom().item(PET_STORE_DB.put(l, createdPet));
    }

    @Override
    public Uni<Response> deletePet(Long petId, String apiKey) {
        return Uni.createFrom().item(Response.noContent().build());
    }

    @Override
    public Uni<List<Pet>> findPetsByStatus(String status) {
        List<Pet> pets = new ArrayList<>();
        for (Map.Entry<Long, Pet> entry : PET_STORE_DB.entrySet()) {
            if (entry.getValue().getStatus() == Pet.StatusEnum.fromString(status)) {
                pets.add(entry.getValue());
            }
        }
        return Uni.createFrom().item(pets);
    }

    @Override
    public Uni<List<Pet>> findPetsByTags(List<String> tags) {
        Set<String> allTags = new HashSet<>(tags);
        List<Pet> pets = new ArrayList<>();
        for (Map.Entry<Long, Pet> entry : PET_STORE_DB.entrySet()) {
            if (entry.getValue().getTags().stream().anyMatch(t -> allTags.contains(t.getName()))) {
                pets.add(entry.getValue());
            }
        }
        return Uni.createFrom().item(pets);
    }

    @Override
    public Uni<Pet> getPetById(Long petId) {
        return Uni.createFrom().item(PET_STORE_DB.get(petId));
    }

    @Override
    public Uni<Pet> updatePet(Pet pet) {
        return Uni.createFrom().item(PET_STORE_DB.compute(pet.getId(), (aLong, pet1) -> pet));
    }

    @Override
    public Uni<Response> updatePetWithForm(Long petId, String name, String status) {
        Pet computed = PET_STORE_DB.compute(petId, (aLong, pet) -> pet.status(Pet.StatusEnum.fromString(status)).name(name));
        return Uni.createFrom().item(Response.ok().entity(computed).build());
    }

    @Override
    public Uni<ModelApiResponse> uploadFile(Long petId, String additionalMetadata, File body) {
        Log.info("Ignoring the file: {}" + body);
        return Uni.createFrom().item(new ModelApiResponse().code(200).message("Success").type("SUCCESS"));
    }
}

See the integration-tests module for more information of how to use this extension. Please be advised that the extension is on experimental, early development stage.

Configuration Properties

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.openapi.generator.spec

This property is deprecated: Use quarkus.openapi.generator.server.<tool>.spec instead.

The OpenAPI specification filename.

Environment variable: QUARKUS_OPENAPI_GENERATOR_SPEC

string

quarkus.openapi.generator.input-base-dir

This property is deprecated: Use quarkus.openapi.generator.server.<tool>.input-base-dir instead.

The input base dir where the OpenAPI specification is.

Environment variable: QUARKUS_OPENAPI_GENERATOR_INPUT_BASE_DIR

string

quarkus.openapi.generator.reactive

This property is deprecated: Use quarkus.openapi.generator.server.<tool>.use-reactive instead.

Whether it must generate with reactive code.

Environment variable: QUARKUS_OPENAPI_GENERATOR_REACTIVE

boolean

quarkus.openapi.generator.builders

This property is deprecated: quarkus.openapi.generator.server.<tool>.use-builders instead.

Whether it must generate builders for properties.

Environment variable: QUARKUS_OPENAPI_GENERATOR_BUILDERS

boolean

quarkus.openapi.generator.base-package

This property is deprecated: Use quarkus.openapi.generator.server.<tool>.base-package instead.

The base package to be used to generated sources.

Environment variable: QUARKUS_OPENAPI_GENERATOR_BASE_PACKAGE

string

quarkus.openapi.generator.use-bean-validation

This property is deprecated: Use quarkus.openapi.generator.server.<tool>.use-bean-validation instead.

Whether it must generate resources and beans using bean validation (JSR-303).

Environment variable: QUARKUS_OPENAPI_GENERATOR_USE_BEAN_VALIDATION

boolean

quarkus.openapi.generator.server.use

The generator to be used for generating the server code.

Possible values are: apicurio or openapitools.

By default, is apicurio.

Environment variable: QUARKUS_OPENAPI_GENERATOR_SERVER_USE

string

apicurio

quarkus.openapi.generator.server.spec

The OpenAPI specification filename.

Environment variable: QUARKUS_OPENAPI_GENERATOR_SERVER_SPEC

string

quarkus.openapi.generator.server.input-base-dir

The input base dir where the OpenAPI specification is.

Environment variable: QUARKUS_OPENAPI_GENERATOR_SERVER_INPUT_BASE_DIR

string

src/main/resources/openapi

quarkus.openapi.generator.server.use-reactive

Whether it must generate with reactive code.

Environment variable: QUARKUS_OPENAPI_GENERATOR_SERVER_USE_REACTIVE

boolean

false

quarkus.openapi.generator.server.use-builder

Whether it must generate builders for properties.

Environment variable: QUARKUS_OPENAPI_GENERATOR_SERVER_USE_BUILDER

boolean

false

quarkus.openapi.generator.server.base-package

The base package to be used to generated sources.

Environment variable: QUARKUS_OPENAPI_GENERATOR_SERVER_BASE_PACKAGE

string

org.acme

quarkus.openapi.generator.server.use-bean-validation

Whether it must generate resources and beans using bean validation (JSR-303).

Environment variable: QUARKUS_OPENAPI_GENERATOR_SERVER_USE_BEAN_VALIDATION

boolean

false