Quarkus - OpenAPI Generator - Server - Apicurio

Quarkus' extension for generation of server Stubs based on OpenAPI specification files.

This server extension has support for two code generation tools:

This extension is for REST code generation for server side only.

Want to contribute? Great! We try to make it easy, and all contributions, even the smaller ones, are more than welcome. This includes bug reports, fixes, documentation, examples…​ But first, read this page.

Apicurio vs OpenAPITools

The following table compares the Apicurio and OpenAPITools code generators.

Aspect Apicurio Code Generator OpenAPITools Code Generator

How it is selected

Explicit via quarkus.openapi.generator.server.use=apicurio

Explicit via quarkus.openapi.generator.server.use=openapitools

Customization mechanism

OpenAPI specification extensions (x-codegen-*)

Configuration properties

Customization location

OpenAPI document (root, paths, schemas, properties)

Not supported

Fine-grained control per operation

Yes (x-codegen-async, x-codegen-returnType)

Yes (x-use-rest-response, x-return-type) for RestResponse support. x-return-type must use the fully qualified class name.

Fine-grained control per schema

Yes (x-codegen-package, x-codegen-annotations, x-codegen-extendsClass, etc.)

Not supported

Add annotations to generated beans

Yes (x-codegen.bean-annotations, x-codegen-annotations)

Yes (x-class-extra-annotation)

Add annotations to method parameters

Yes (paths.*.parameters[].x-codegen-annotations)

Not supported

Async / reactive support

Per operation via x-codegen-async or globally using quarkus.openapi.generator.server.use-reactive=true. The apicurio allows you to use CompletionStage or Uni.

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

Custom return types

Yes (x-codegen-returnType)

RestResponse or model class. RestResponse allows full control over status codes and headers (e.g., public org.jboss.resteasy.reactive.RestResponse<Pet> createPet(Pet request)). Per-operation via x-use-rest-response or x-return-type vendor extensions. Use the fully qualified class name with x-return-type.

Context root configuration

Via OpenAPI (x-codegen.contextRoot)

Not supported

Date/time formatting control

Yes (x-codegen.suppress-date-time-formatting, x-codegen-formatPattern)

Not supported

Inline schemas instead of generating classes

Yes (x-codegen-inline, x-codegen-inlined)

Not supported

Override generated Java type

Yes (x-codegen-type)

Not supported

Extend a base class

Yes (x-codegen-extendsClass)

Not supported

Package customization

Per schema via x-codegen-package, globally via quarkus.openapi.generator.server.base-package, or per configured spec via quarkus.openapi.generator.server.spec.<id>.base-package

Globally via quarkus.openapi.generator.server.base-package or per configured spec via quarkus.openapi.generator.server.spec.<id>.base-package

OpenAPI spec location

src/main/resources/openapi (configurable via quarkus.openapi.generator.server.input-base-dir or quarkus.openapi.generator.server.spec.<id>.input-base-dir)

src/main/resources/openapi (configurable via quarkus.openapi.generator.server.input-base-dir or quarkus.openapi.generator.server.spec.<id>.input-base-dir)

Supported OpenAPI formats

JSON, YAML, YML

JSON, YAML, YML

Generated sources location

target/generated-sources/jaxrs

target/generated-sources/quarkus-openapi-generator-server

Customization philosophy

Spec-driven, fine-grained, declarative

Property-driven, coarse-grained

Extension maturity

Preview

Experimental / early development

Both generators support multi-file OpenAPI documents with relative $ref entries. Keep the referenced files under the same input base directory as the entry spec so they can be resolved during generation.

You can also generate multiple server stubs in a single project by configuring one block per spec under quarkus.openapi.generator.server.spec.<id>.*. The <id> can either be the sanitized relative file name, such as petstore_openapi_json, or an alias when you also set quarkus.openapi.generator.server.spec.<id>.spec=<file>.

When using per-spec configuration (quarkus.openapi.generator.server.spec.<id>.*), any OpenAPI specification files found in the input base directory that are not explicitly configured will be automatically discovered and generated using default values (e.g., base-package=org.acme, use-builders=true). To exclude files from auto-discovery (such as shared reference files like common-spec.yaml), use the quarkus.openapi.generator.server.exclude property.

Using Client and Server Generators Together

When using both the Client and Server generators in the same project, note that they have different default input directories:

| Generator | Default Input Directory | |-----------|-------------------------| | Client | src/main/openapi | | Server | src/main/resources/openapi |

This means if you place your OpenAPI spec in src/main/openapi, the client generator will find it automatically, but the server generator will not.

Option 1: Configure Server Generator to Use Client’s Directory

Add to src/main/resources/application.properties:

quarkus.openapi.generator.server.input-base-dir=src/main/openapi
quarkus.openapi.generator.server.use=apicurio
# or openapitools
quarkus.openapi.generator.server.spec=your-spec.yaml

Option 2: Use Separate Directories

Keep specs in their default locations: - Client specs: src/main/openapi/ - Server specs: src/main/resources/openapi/

Option 3: Explicit Spec Configuration (Recommended)

For full control, explicitly configure both generators:

# Client generator (uses src/main/openapi by default)
quarkus.openapi-generator.codegen.spec.your-spec_yaml.base-package=org.acme.client

# Server generator (explicit config)
quarkus.openapi.generator.server.use=apicurio
quarkus.openapi.generator.server.spec=your-spec.yaml
quarkus.openapi.generator.server.input-base-dir=src/main/openapi
quarkus.openapi.generator.server.base-package=org.acme.server

Important Notes

  • The quarkus.openapi.generator.server.use property is required for server generation (values: apicurio or openapitools)

  • Without explicit server config, running mvn quarkus:generate-code may only generate client code with a warning

  • Run mvn compile or mvn quarkus:generate-code after configuring to generate both client and server code

Multiple Files Support

Both Apicurio and OpenAPITools generators support multiple OpenAPI files in the input directory:

  • Multi-file specs: An entry spec can use relative $ref to reference other YAML/JSON files in the same input directory

  • Auto-discovery: All .json, .yaml, .yml files in input-base-dir are automatically discovered and generated with defaults (base-package=org.acme, use-builders=true)

  • Filtering: Use quarkus.openapi.generator.server.include and quarkus.openapi.generator.server.exclude to control which files are processed

  • Per-spec config: Use quarkus.openapi.generator.server.spec.<id>.* to customize each spec individually (the <id> is the sanitized relative file name, e.g., petstore_openapi_json)

To exclude shared reference files (like common-spec.yaml) from auto-discovery, use the quarkus.openapi.generator.server.exclude property.

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