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.

All OpenAPI specification files found in the input base directory are automatically discovered and generated. You can explicitly configure a spec with the following property:

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

If no explicit specification is configured, the extension generates code for all OpenAPI files in the input base directory using default values. When using per-spec configuration (quarkus.openapi.generator.server.spec.<id>.*), any unconfigured spec files are also auto-discovered and generated with defaults.

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

Multi-file specifications

OpenAPITools can generate from entry specs that use relative $ref values across multiple YAML or JSON files. Place the full spec tree under the configured input base directory and point the generator at the entry document.

For example:

quarkus.openapi.generator.server.use=openapitools
quarkus.openapi.generator.server.input-base-dir=src/main/resources/openapi
quarkus.openapi.generator.server.spec=module1.yaml

If module1.yaml contains $ref: './common/common-spec.yaml#/components/schemas/CommonPet', the referenced file is resolved automatically as long as common/common-spec.yaml is present under the same base directory.

Multiple generated servers

You can generate more than one server stub in the same build by configuring one block per spec:

quarkus.openapi.generator.server.use=openapitools
quarkus.openapi.generator.server.spec.petstore_openapi_json.base-package=org.acme.api.petstore
quarkus.openapi.generator.server.spec.simple_server_yaml.base-package=org.acme.api.animals

The identifier after server.spec. may also be an alias when you want to point explicitly to a file or override its input directory:

quarkus.openapi.generator.server.use=openapitools
quarkus.openapi.generator.server.spec.petstore.spec=petstore-openapi.json
quarkus.openapi.generator.server.spec.petstore.base-package=org.acme.api.petstore
quarkus.openapi.generator.server.spec.animals.input-base-dir=src/main/resources/other-openapi
quarkus.openapi.generator.server.spec.animals.spec=animals.yaml
quarkus.openapi.generator.server.spec.animals.base-package=org.acme.api.animals

Properties defined under quarkus.openapi.generator.server.spec.<id>. override the global server. values for that specific generated server.

Filtering auto-discovered specifications

When using per-spec configuration or when no specification is explicitly configured, the extension auto-discovers all OpenAPI files in the input base directory. You can filter which files are processed using the include and exclude properties:

quarkus.openapi.generator.server.include=petstore-openapi.json,simple-server.yaml

or

quarkus.openapi.generator.server.exclude=common-spec.yaml,shared-models.yaml

The include and exclude properties match against file names only (not full paths). When include is set, only the listed files are processed. When exclude is set, the listed files are skipped. Both can be used together.

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

Returning Response Objects

By default, the generator uses the model class or void as the return type for operations. If you need more control over the response, such as setting custom headers or status codes (e.g., 201 Created), you can enable the use of org.jboss.resteasy.reactive.RestResponse:

This property only applies when using the OpenAPITools code generator (i.e., when quarkus.openapi.generator.server.use is set to openapitools).

 
quarkus.openapi.generator.server.use-rest-response=true

You can also configure this at the operation level by using one of the following vendor extensions: * x-return-type: org.jboss.resteasy.reactive.RestResponse (must be fully qualified) * x-use-rest-response: true

paths:
  /pet:
    post:
      operationId: createPet
      x-return-type: org.jboss.resteasy.reactive.RestResponse
      # Alternatively:
      # x-use-rest-response: true
      responses:
        "201":
          description: Created

When enabled globally or at the operation level, the generated methods will look like this:

public org.jboss.resteasy.reactive.RestResponse<Pet> createPet(Pet request);

If you combine it with use-reactive=true, the return type will be:

public Uni<org.jboss.resteasy.reactive.RestResponse<Pet>> createPet(Pet request);

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.

x-smallrye-profile-<profileName>

You can add [SmallRye profile-specific vendor extensions](https://github.com/smallrye/smallrye-open-api?tab=readme-ov-file#x-smallrye-profile-profilename) directly to an OpenAPI operation, and the OpenAPITools server generator will propagate them to the generated resource method.

You must add the dependency below to your project, as the org.eclipse.microprofile.openapi.annotations.* annotations are required at compile time. Without it, the generated code will not compile:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-openapi</artifactId>
</dependency>

When one or more x-smallrye-profile-<profileName> entries are present on an operation, the generated method is annotated with @org.eclipse.microprofile.openapi.annotations.extensions.Extensions and one @Extension entry per matching vendor extension.

Example:

paths:
  /pet/findByTags:
    get:
      operationId: findPetsByTags
      x-smallrye-profile-admin: ""
      x-smallrye-profile-order: ""
      x-smallrye-profile-user: ""

This generates an annotation similar to:

@org.eclipse.microprofile.openapi.annotations.extensions.Extensions({
    @org.eclipse.microprofile.openapi.annotations.extensions.Extension(name = "x-smallrye-profile-admin", value = ""),
    @org.eclipse.microprofile.openapi.annotations.extensions.Extension(name = "x-smallrye-profile-order", value = ""),
    @org.eclipse.microprofile.openapi.annotations.extensions.Extension(name = "x-smallrye-profile-user", value = "")
})

The generated entries are sorted by profile name to keep the output deterministic.

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

quarkus.openapi.generator.server.use-rest-response

Whether the generated server methods should use org.jboss.resteasy.reactive.RestResponse<T> as the return type for single-response endpoints. When enabled, methods return RestResponse<Model> (or Uni<RestResponse<Model>> in reactive mode), allowing implementors to control the HTTP response status code (e.g. 201 Created). Streaming endpoints are out of scope for this flag. This property only applies when using the openapitools code generator (i.e. when quarkus.openapi.generator.server.use is set to openapitools). By default this is false, preserving backward-compatible return types.

Environment variable: QUARKUS_OPENAPI_GENERATOR_SERVER_USE_REST_RESPONSE

boolean

false

quarkus.openapi.generator.server.skip-if-unchanged

Whether to skip generation when the persisted fingerprint of the OpenAPI specification and relevant generation configuration matches the previous run.

Environment variable: QUARKUS_OPENAPI_GENERATOR_SERVER_SKIP_IF_UNCHANGED

boolean

false

quarkus.openapi.generator.server.include

List of OpenAPI file names to include for code generation. When set, only the listed files are processed by the auto-discovery mechanism.

Environment variable: QUARKUS_OPENAPI_GENERATOR_SERVER_INCLUDE

list of string

quarkus.openapi.generator.server.exclude

List of OpenAPI file names to exclude from code generation. When set, the listed files are skipped by the auto-discovery mechanism. This is useful for excluding shared reference files (e.g., common-spec.yaml) that are not standalone specifications.

Environment variable: QUARKUS_OPENAPI_GENERATOR_SERVER_EXCLUDE

list of string

quarkus.openapi.generator.server.operation-ids."operation-ids".return-type

The name of the method parameter that should be used to return the response from the operation.

Environment variable: QUARKUS_OPENAPI_GENERATOR_SERVER_OPERATION_IDS__OPERATION_IDS__RETURN_TYPE

string

required