v/28.0.0
openapi: 3.0.0 info: title: Pets API version: 1.0.0 paths: '/pets': get: operationId: listPets summary: List all pets responses: '200': description: A list of pets content: application/json: schema: type: array items: $ref: '#/components/schemas/Pet' post: operationId: createPet summary: Create a pet requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Pet' responses: '201': description: Pet created content: application/json: schema: $ref: '#/components/schemas/Pet' '/pets/{petId}': get: operationId: getPet summary: Get a pet by ID parameters: - name: petId in: path required: true schema: type: string responses: '200': description: A single pet content: application/json: schema: $ref: '#/components/schemas/Pet' '404': description: Pet not found components: schemas: Pet: type: object required: - id - name - type properties: id: type: string name: type: string type: type: string enum: - dog - cat age: type: integer
What to generate
genTypes
HTTP_MODELS - Jackson annotated data classes to represent the schema objects defined in the input.
CONTROLLERS - Spring / Micronaut / Ktor HTTP controllers for each of the endpoints defined in the input.
CLIENT - Simple http rest client.
QUARKUS_REFLECTION_CONFIG - This options generates the reflection-config.json file for quarkus integration projects
Model Options
serializationLibrary
JACKSON - Use Jackson 2 for serialization and deserialization
JACKSON_2 - Use Jackson 2 for serialization and deserialization
JACKSON_3 - Use Jackson 3 for serialization and deserialization
KOTLINX_SERIALIZATION - Use kotlinx.serialization for serialization and deserialization
instantLibrary
KOTLINX_INSTANT - Use kotlinx.datetime Instant in generated classes (default)
KOTLIN_TIME_INSTANT - Use kotlin.time Instant in generated classes
jacksonNullabilityMode
NONE - Default Jackson behaviour
ENFORCE_OPTIONAL_NON_NULL - Omit null values for optional non-null fields
ENFORCE_REQUIRED_NULLABLE - Include null values for required nullable fields
STRICT - Combines ENFORCE_OPTIONAL_NON_NULL and ENFORCE_REQUIRED_NULLABLE for strictest contract enforcement
modelOptions
EXCLUDE_READ_ONLY - Exclude readOnly properties and honour requiredness of retained writeOnly properties
EXCLUDE_WRITE_ONLY - Exclude writeOnly properties and honour requiredness of retained readOnly properties
X_EXTENSIBLE_ENUMS - This option treats x-extensible-enums as enums
JAVA_SERIALIZATION - This option adds Java Serializable interface to the generated models
QUARKUS_REFLECTION - This option adds @RegisterForReflection to the generated models. Requires dependency "'io.quarkus:quarkus-core:+"
MICRONAUT_INTROSPECTION - This option adds @Introspected to the generated models. Requires dependency "'io.micronaut:micronaut-core:+"
MICRONAUT_REFLECTION - This option adds @ReflectiveAccess to the generated models. Requires dependency "'io.micronaut:micronaut-core:+"
MICRONAUT_SERDEABLE - This option adds @Serdeable to the generated models. Requires dependency "'io.micronaut.serde:micronaut-serde-jackson:+"
INCLUDE_COMPANION_OBJECT - This option adds a companion object to the generated models.
NON_NULL_MAP_VALUES - This option makes map values non-null. The default (since v15) and most spec compliant is make map values nullable
FAULT_TOLERANT_ENUMS - This option adds an UNRECOGNIZED enum entry as a fallback for unmapped values, preventing deserialization exceptions. If jackson is used, the deserialization option **READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE** will need to be enabled as well
FAULT_TOLERANT_OPEN_ENUMS - This option converts the "open enum" pattern (an anyOf combining a string enum with an open type: string) into a fault-tolerant enum, i.e. an enum carrying the declared values plus an UNRECOGNIZED fallback, instead of collapsing the type to a plain String. Behaves like FAULT_TOLERANT_ENUMS for the affected enums
modelAdditionalAnnotations
One fully qualified annotation class name per line; annotations must not require arguments
modelSuffix
typeOverrides
DATETIME_AS_INSTANT - Use Instant as the datetime type. Defaults to OffsetDateTime
DATETIME_AS_LOCALDATETIME - Use LocalDateTime as the datetime type. Defaults to OffsetDateTime
DATETIME_AS_OFFSETDATETIME - Use OffsetDateTime as the datetime type. Default for Jackson
BYTE_AS_STRING - Ignore string format byte and use String as the type
BYTE_AS_BYTEARRAY - Use ByteArray as the byte type. Default
BINARY_AS_STRING - Ignore string format binary and use String as the type
BINARY_AS_BYTEARRAY - Use ByteArray as the binary type. Default
URI_AS_STRING - Ignore string format uri and use String as the type
URI_AS_URI - Use java.net.URI as the uri type. Default
UUID_AS_STRING - Ignore string format uuid and use String as the type
UUID_AS_UUID - Use java.util.UUID as the uuid type. Default
DATE_AS_STRING - Ignore string format date and use String as the type
DATE_AS_LOCALDATE - Use java.time.LocalDate as the date type. Default for Jackson
DATE_AS_KOTLINXLOCALDATE - Use kotlinx.datetime.LocalDate as the date type. Default for kotlinx.serialization
DATETIME_AS_STRING - Ignore string format date-time and use String as the type
BYTEARRAY_AS_INPUTSTREAM - Use InputStream as ByteArray type. Defaults to ByteArray
ANY_AS_JSONELEMENT - Use kotlinx.serialization.json.JsonElement for untyped (any) schemas and JsonObject for untyped objects. Requires the KOTLINX_SERIALIZATION serialization library. Defaults to Any
ANY_AS_ANY - Use Any as the untyped (any) type. Default
customTypeMappings
One mapping per line: type:format=KotlinFqcn, optionally followed by ;kotlinx=SerializerFqcn
Client Options
clientTarget
OK_HTTP - Generate OkHttp client.
OPEN_FEIGN - Generate OpenFeign client.
SPRING_HTTP_INTERFACE - Generate Spring HTTP Interface.
KTOR - Generate Ktor client.
clientOptions
SUSPEND_MODIFIER - This option adds the suspend modifier to the generated client functions (only for OpenFeign clients)
SPRING_RESPONSE_ENTITY_WRAPPER - This option adds the Spring-ResponseEntity generic around the response to be able to get response headers and status (only for OpenFeign clients).
SPRING_CLOUD_OPENFEIGN_STARTER_ANNOTATION - This option adds the @FeignClient annotation to generated client interface
GROUP_BY_TAG - This option groups clients based on the first tag rather than paths
OKHTTP_NON_NULL_RESPONSE_PAYLOADS - This option makes ApiResponse.data non-null. Responses declared with a body must return one: a missing body, or one that deserializes to null, throws ApiException. An operation that declares both a body response and an empty success response (e.g. 200 and 204) throws on the empty success. Binary responses return an empty ByteArray for an empty body (only for OkHttp clients)
RESPONSE_MEDIA_TYPE_FUNCTIONS - This option adds, for each operation whose success responses declare a different JSON schema per media type, one function per media type. The function always sends that media type as the Accept header and returns that schema's type instead of JsonNode. Its name is the operation's function name plus the media subtype, e.g. getItemsVndCustomJson for application/vnd.custom+json (only for OkHttp, OpenFeign and Spring HTTP Interface clients)
DYNAMIC_BASE_URL - This option makes ApiConfiguration.basePath empty, allowing you to set the base URL at runtime (only for Ktor clients)
OPENAPI_BEARER_AUTHENTICATION - Adds operation-specific Bearer token helpers for OpenAPI HTTP Bearer security schemes
OPENAPI_OAUTH2_AUTHENTICATION - Adds operation-specific OAuth2 access-token helpers that pass required scopes to a caller-provided token provider
openfeignClientName
Server Options
controllerTarget
SPRING - Generate for Spring framework.
MICRONAUT - Generate for Micronaut framework.
KTOR - Generate for Ktor server.
controllerOptions
SUSPEND_MODIFIER - This option adds the suspend modifier to the generated controller functions
AUTHENTICATION - This option adds the authentication parameter to the generated controller functions
GROUP_BY_TAG - This option groups controllers based on the first tag rather than paths
COMPLETION_STAGE - This option makes generated controller functions have Type CompletionStage
(works only with Spring Controller generator). Can be overridden per operation using the OpenAPI extension x-async-support: true|false
SSE_EMITTER - This option makes generated controller functions have Type SseEmitter (works only with Spring Controller generator)
Operation Options
operationIdTransform
Validation Options
validationLibrary
JAVAX_VALIDATION - Use javax.validation annotations in generated model classes
JAKARTA_VALIDATION - Use jakarta.validation annotations in generated model classes (default)
NO_VALIDATION - Use no validation annotations in generated model classes
External References
externalRefResolutionMode
TARGETED - Generate models only for directly referenced schemas in external API files.
AGGRESSIVE - Referencing any schema in an external API file triggers generation of every external schema in that file.
Output Options
outputOptions
ADD_FILE_DISCLAIMER - This option adds a disclaimer to the generated files.
ADD_GENERATED_ANNOTATION - Annotate generated types and top-level functions with javax.annotation.processing.Generated.
// Files will appear here
// Output will appear here