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)

Not supported

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)

Not supported

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)

Only Multi or model class (public Pet createPet(Pet request).

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 or quarkus.openapi.generator.server.base-package

Global base package via quarkus.openapi.generator.server.base-package

OpenAPI spec location

src/main/resources/openapi (configurable via quarkus.openapi.generator.server.input-base-dir)

src/main/resources/openapi (configurable via quarkus.openapi.generator.server.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

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