apigenie-generator server spring
Tier 1 · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · Verification
Generate a Spring Boot server, or Spring Cloud / HTTP interface clients, in Java.
From an AsyncAPI document, the command generates a Spring Boot Kafka application instead; see
apigenie-generator server spring (AsyncAPI).
Usage
apigenie-generator server spring [...OPTIONS] INPUT_FILE
Description
The generator produces the same code as the spring generator of
openapi-generator, and accepts the same options. A project
generated by openapi-generator can be regenerated by API Genie, and vice versa.
The input is an OpenAPI 3.0, 3.1 or 3.2 document or, since 0.12.0, a Swagger 2.0 document (see
Swagger 2.0 input). Bundle a document that
references other files with apigenie bundle first.
It supports three libraries:
spring-boot(default): a Spring Boot application, with API interfaces (PetApi), controllers implementing them (PetApiController), optional delegates (PetApiDelegate), models, SpringDoc configuration and a Mavenpom.xmlspring-cloud: Feign clients (PetApiClient) and their security configurationspring-http-interface:@HttpExchangeinterfaces and a configurator creating their proxies
The spring-cloud and spring-http-interface clients are generated by the writers of
apigenie-generator client java (its feign and
http-interface libraries), which also generates standalone clients on Spring’s RestClient and
RestTemplate.
The generated project contains:
pom.xmlandREADME.md- the application class,
RFC3339DateFormat,application.propertiesand a copy of the OpenAPI document insrc/main/resources/openapi.yaml(servers) - API interfaces, grouped by the first segment of their paths or, with
useTags, by tags - models: classes with fluent setters,
equals,hashCodeandtoString, enums, interfaces foroneOfschemas, and class hierarchies forallOfschemas with discriminators .openapi-generator/FILES(the list of generated files) and.openapi-generator/VERSION
Controllers (*ApiController.java) and .openapi-generator-ignore are generated only if they
don’t exist, so they can be implemented and edited. .openapi-generator/FILES lists the
controllers in both cases, so generating again doesn’t change it (since 0.12.0). Files listed in
.openapi-generator-ignore (which uses the syntax of .gitignore) are not written.
The vendor extensions the generator reads are listed in “Extensions”.
Differences from openapi-generator:
useSpringBoot3istrueby default- generated files are marked with
@Generated(value = "API Genie") @Generatedhas nodateunlesshideGenerationTimestampisfalse(since 0.12.0)- unknown options are errors, not ignored
- since 0.12.0, Swagger 2.0 polymorphism becomes an interface that its shapes implement, with
@JsonSubTypesfor theirx-discriminator-value, where openapi-generator writes a parent class that they extend - schemas whose names give the same class name (e.g.
app-permissionsand an inlineapp_permissions) get classes with numeric suffixes, e.g.AppPermissions1
Since 0.12.0, the generator also covers:
- callbacks, as
@Callbackannotations on the operations that register them, and webhooks, as anApiWebhooksinterface annotated with@Webhooks(both needannotationLibrary: swagger2, the default with SpringDoc;apiFirstleaves outApiWebhooks). They document the requests the server sends. The generator writes no code that sends them. The SpringDoc versions in the generatedpom.xml(2.6.0, or 1.6.14 for Spring Boot 2) don’t read@Webhooks deepObjectquery parameters of objects and maps, read by a generated argument resolver (@DeepObjectParameter) that answers 400 when a value doesn’t convert to the type of its property or two keys conflict, and withuseBeanValidationwhen the object isn’t valid; keys the model doesn’t have are ignored- streaming responses (
text/event-stream, JSON Lines, JSON sequences) of arrays, returned as aFluxof their items; Spring MVC writes server-sent events andapplication/x-ndjsonitem by item, andapplication/jsonl,application/x-jsonlinesandapplication/json-seqonce theFluxcompletes - strings with a non-JSON
contentMediaTypeand nocontentEncodingas files and binary bodies, as withformat: binary(contentMediaTypeAsBinary, on by default) - the flows of OAuth 2 schemes and
mutualTLSschemes in the SpringDoc configuration writeOnlyproperties, documented withSchema.AccessMode.WRITE_ONLY- tuples,
patternProperties,multipleOf(a generatedMultipleOfconstraint) and conditional schemas (@AssertTruemethods), modelled as inapigenie-generator client java; theMultipleOfconstraint and the@AssertTruemethods needuseBeanValidation
Limitations:
deepObjectparameters of other types are read as plain query parameters.- Streaming responses whose
schemaisn’t an array are returned as plain bodies. A response whose first media type has only anitemSchemagets no body (aVoidreturn type). - Server-sent events carry each item as their
data, withouteventorid. - With
reactive, WebFlux writes server-sent events andapplication/x-ndjson; the generator adds no encoder ofapplication/jsonl,application/x-jsonlinesorapplication/json-seq. - A JSON Lines or JSON sequence request body with an array
schemais aListthat no generated converter reads. With only anitemSchema, the method takes the type of the body’s first media type, and has no body parameter when that media type has noschemaeither. - Strings with a
contentEncodingstayString. - The SpringDoc configuration leaves out the device authorization flow of OAuth 2 schemes, which the swagger-core models it builds have no field for.
Extensions
| Extension | Effect |
|---|---|
x-class-extra-annotation |
annotations of the class of a schema, e.g. ['@Entity'] |
x-implements |
interfaces the class of a schema implements |
x-field-extra-annotation |
annotations of the field of a property, or of the method parameter of a parameter |
x-extra-annotation |
annotations of the getter of a property |
x-setter-extra-annotation |
annotations of the setter of a property |
x-pattern-message, x-size-message, x-minimum-message, x-maximum-message |
message of the @Pattern, @Size, @Min/@DecimalMin and @Max/@DecimalMax annotations of a property or a parameter, on its schema, and since 0.12.0 on the parameter itself, as in Swagger 2.0 documents |
x-jackson-json-include-policy |
@JsonInclude policy of a property, e.g. non_empty (none for no annotation) |
x-jackson-json-setter-nulls |
@JsonSetter(nulls = ...) of a property, e.g. skip (none for no annotation) |
x-enum-varnames |
names of the constants of an enum |
x-enum-descriptions |
Javadoc of the constants of an enum |
x-parent |
true makes a schema the superclass of the schemas extending it with allOf, without a discriminator |
x-discriminator-value |
the discriminator value of a subclass in @JsonSubTypes (default: the name of its schema) |
x-jackson-default-impl |
defaultImpl of the @JsonTypeInfo of a class with a discriminator |
x-defaultMapping |
defaultMapping of a discriminator in OpenAPI 3.0 and 3.1 documents: the defaultImpl of @JsonTypeInfo, without x-jackson-default-impl |
x-codegen-request-body-name |
on an operation or its request body: the name of the body parameter |
x-apigenie.codegen.controller-name |
on an operation: the API class of the operation, instead of its tag or path |
x-apigenie.codegen.action-name |
name of the method of an operation, instead of its operationId |
x-apigenie.codegen.disabled |
true on an operation or its path item leaves the operation out, with skipDisabled |
x-internal |
true on an operation leaves it out |
x-operation-extra-annotation |
annotations of the method of an operation (not with spring-http-interface) |
x-version-param |
true on a header or query parameter adds it to the headers or params of the @RequestMapping (not with spring-http-interface) |
x-spring-paginated |
true replaces the page, size and sort parameters of an operation with a Pageable; false keeps them even with autoXSpringPaginated |
x-spring-provide-args |
further arguments of the method of an operation, e.g. ['@RequestAttribute("tenant") String tenant'] (not with spring-http-interface) |
The extensions can live in an overlay for this target instead of in the document, e.g.
spring.overlay.yaml:
overlay: 1.0.0
info:
title: Spring annotations
version: 1.0.0
actions:
- target: $.paths['/pets'].get
update:
x-spring-paginated: true
- target: $.components.schemas.Pet
update:
x-class-extra-annotation: ['@com.acme.Audited']
apigenie-generator server spring openapi.yaml --overlay spring.overlay.yaml -o out
Options
-c, –config
Path to the configuration file to use. See the “Configuration” section for more information.
–overlay OVERLAY
Path to an OpenAPI Overlay (1.0 to 1.2) applied to the input before generating, e.g. one setting the
extensions of the “Extensions” section. Can be repeated: the overlays apply in order, after those
listed under commands.generate.server_spring.overlay in the configuration file (with paths
relative to it). Warnings and errors about a value an overlay set point to the overlay.
–strict
Makes an overlay action whose target selects nothing an error (exit status 2, nothing is generated)
instead of a warning (OVERLAY:LINE:COL: action #N (TARGET) selects no nodes.).
–check
Writes nothing: compares what the generator would write with the output directory, prints the files that would be created or changed, and exits with 1 when there are any (since 0.12.0). See Check that generated code is up to date.
-o, –output
Directory where the project is generated.
–package-name
Base package of the generated code, e.g. com.example. API, model and configuration classes are
generated in its api, model and configuration sub-packages, unless apiPackage,
modelPackage or configPackage are set.
–package-version
Version of the generated project (artifactVersion). Defaults to the version of the API.
-p, –property NAME=VALUE
Sets a generator option (see below), e.g. -p delegatePattern=true. Options given on the command
line take precedence over the configuration file. Mapping options take comma-separated lists,
e.g. -p typeMappings=DateTime=java.time.Instant,UUID=String. Applies to OpenAPI documents only;
using it with an AsyncAPI document is an error.
Configuration
Options can also be set in the configuration file, either directly or in an
additionalProperties section, like in configuration files of openapi-generator. The asyncapi
key holds the options of the generation from AsyncAPI documents (see
apigenie-generator server spring (AsyncAPI)):
version: '1.0'
commands:
generate:
server_spring:
basePackage: com.example
delegatePattern: true
typeMappings:
DateTime: java.time.Instant
| Option | Description |
|---|---|
library |
Library template: spring-boot (server), spring-cloud (Feign client) or spring-http-interface (HTTP interface client) |
basePackage |
Base package for generated code |
invokerPackage |
Alias of basePackage |
apiPackage |
Package for generated API classes |
modelPackage |
Package for generated models |
configPackage |
Package for generated configuration classes |
groupId |
groupId in the generated pom.xml |
artifactId |
artifactId in the generated pom.xml |
artifactVersion |
Artifact version in the generated pom.xml |
artifactDescription |
Artifact description in the generated pom.xml |
artifactUrl |
Artifact URL in the generated pom.xml |
licenseName |
License name in the generated pom.xml |
licenseUrl |
License URL in the generated pom.xml |
developerName |
Developer name in the generated pom.xml |
developerEmail |
Developer email in the generated pom.xml |
developerOrganization |
Developer organization in the generated pom.xml |
developerOrganizationUrl |
Developer organization URL in the generated pom.xml |
scmConnection |
SCM connection in the generated pom.xml |
scmDeveloperConnection |
SCM developer connection in the generated pom.xml |
scmUrl |
SCM URL in the generated pom.xml |
parentGroupId |
groupId of the parent pom |
parentArtifactId |
artifactId of the parent pom |
parentVersion |
Version of the parent pom |
snapshotVersion |
Append -SNAPSHOT to the artifact version |
title |
Server title, used in property names (defaults to info.title) |
serverPort |
Server port (defaults to the port of the first server, or 8080) |
useSpringBoot3 |
Generate code for Spring Boot 3 (jakarta); false means Spring Boot 2 |
useSpringBoot4 |
Generate code for Spring Boot 4 |
useJackson3 |
Use Jackson 3 (tools.jackson) instead of Jackson 2; requires useSpringBoot4 |
optionalAcceptNullable |
Use Optional.ofNullable in fluent setters of Optional properties |
useJspecify |
Use JSpecify (org.jspecify.annotations.Nullable) for null checks |
hideGenerationTimestamp |
Omit the generation date from @Generated annotations (default: true since 0.12.0, false before) |
generationTimestamp |
Timestamp used in @Generated annotations when hideGenerationTimestamp is false |
generatorVersion |
Generator version written into generated files |
dateLibrary |
Date library: java8, java8-localdatetime, joda or legacy |
documentationProvider |
springdoc, source or none |
annotationLibrary |
swagger2 or none |
useSwaggerUI |
Serve Swagger UI |
interfaceOnly |
Generate only API interfaces, without controllers |
delegatePattern |
Delegate request handling to XxxApiDelegate interfaces |
skipDefaultInterface |
Don’t generate default implementations of API methods |
useTags |
Group operations by tag instead of the first path segment |
requestMappingMode |
Where to put the class-level @RequestMapping: controller, api_interface or none |
useResponseEntity |
Wrap return types in ResponseEntity |
useOptional |
Use Optional for optional parameters |
useSpringController |
Annotate API interfaces with @Controller / @RestController |
returnSuccessCode |
Return the success code instead of 501 Not Implemented |
unhandledException |
Declare ‘throws Exception’ on API methods |
apiFirst |
Generate supporting files only |
async |
Return CompletableFuture from API methods |
reactive |
Generate reactive (WebFlux) code |
responseWrapper |
Wrapper of return types: CompletableFuture, Callable, Future, ListenableFuture, DeferredResult or a fully qualified class name |
includeHttpRequestContext |
Add the HTTP request (ServerWebExchange / HttpServletRequest) to API methods |
singleContentTypes |
Use a single content type per operation |
sortParamsByRequiredFlag |
Put required parameters before optional ones |
apiNameSuffix |
Suffix of API class names |
skipDeprecated |
Don’t generate code for deprecated operations |
skipDisabled |
Don’t generate code for operations disabled with x-apigenie |
autoXSpringPaginated |
Add x-spring-paginated to operations with ‘page’, ‘size’ and ‘sort’ query parameters |
substituteGenericPagedModel |
Replace schemas of pages of items (a ‘content’ array and pagination metadata) with PagedModel<T> |
generateSortValidation |
Validate the sort of Pageable parameters against the enum values of ‘sort’ parameters |
generatePageableConstraintValidation |
Validate Pageable parameters against the limits of ‘page’ and ‘size’ parameters |
virtualService |
Generate Virtualan annotations for virtual services |
useSpringSecurityPreAuthorize |
Generate @PreAuthorize annotations from OAuth2/OpenID Connect scopes |
springSecurityAuthorityPrefix |
Prefix of the authorities checked by @PreAuthorize annotations |
implicitHeaders |
Describe header parameters with @Parameters instead of method parameters |
implicitHeadersRegex |
Regular expression of header parameters described with @Parameters |
useHttpServiceProxyFactoryInterfacesConfigurator |
Use a HttpServiceProxyFactory in HttpInterfacesAbstractConfigurator (spring-http-interface) |
clientRegistrationId |
@ClientRegistrationId of API interfaces (spring-http-interface, Spring Boot 4) |
useFeignClientUrl |
Use the url attribute of @FeignClient (spring-cloud) |
useFeignClientContextId |
Use the contextId attribute of @FeignClient (spring-cloud) |
useBeanValidation |
Use Bean Validation annotations |
performBeanValidation |
Use Hibernate Validator annotations |
useSpringBuiltInValidation |
Rely on Spring’s built-in validation (no @Validated) |
additionalNotNullAnnotations |
Add @NotNull to required path and body parameters |
openApiNullable |
Use JsonNullable for nullable properties |
serializableModel |
Make models implement Serializable |
useOneOfInterfaces |
Represent oneOf schemas as interfaces |
useDeductionForOneOfInterfaces |
Deduce oneOf subtypes from their properties |
generatedConstructorWithRequiredArgs |
Generate constructors with required arguments |
generateConstructorWithAllArgs |
Generate constructors with all arguments |
generateBuilders |
Generate builders for models |
sortModelPropertiesByRequiredFlag |
Put required properties first in constructors |
enumPropertyNaming |
Naming of enum constants: MACRO_CASE, original, legacy, camelCase, PascalCase, snake_case or UPPERCASE |
useEnumCaseInsensitive |
Match enum values ignoring case |
withXml |
Add XML annotations to models |
useSealed |
Use sealed classes and interfaces (Java 17+) |
containerDefaultToNull |
Initialize containers with null instead of empty ones |
legacyDiscriminatorBehavior |
Use the legacy discriminator behavior |
disableDiscriminatorJsonIgnoreProperties |
Don’t ignore discriminator properties during serialization |
modelNamePrefix |
Prefix of model names |
camelCaseDollarSign |
Keep the case of the first letter after a leading $ in names |
useEnumValueInterface |
Make enums implement the ValuedEnum interface |
generateJsonIncludeAnnotations |
Add @JsonInclude annotations to model properties |
optionalNonNullPropertyJsonInclude |
@JsonInclude policy of optional, non-nullable properties: NON_NULL, NON_EMPTY, NON_DEFAULT or NONE |
generateJsonSetterNullsAnnotations |
Add @JsonSetter(nulls = …) annotations to optional, non-nullable properties |
optionalNonNullPropertyJsonSetterNulls |
@JsonSetter(nulls = …) mode of optional, non-nullable properties: SKIP or FAIL |
modelNameSuffix |
Suffix of model names |
additionalModelTypeAnnotations |
Annotations added to model classes, separated by semicolons |
additionalEnumTypeAnnotations |
Annotations added to enum classes, separated by semicolons |
additionalOneOfTypeAnnotations |
Annotations added to oneOf interfaces, separated by semicolons |
typeInfoDefaultImpls |
Classes used as defaultImpl of @JsonTypeInfo, by schema name (Schema=Class,…) |
typeMappings |
Mappings of OpenAPI types to Java types (type=JavaType,…) |
importMappings |
Mappings of Java types to imports (Type=package.Type,…) |
schemaMappings |
Mappings of schemas to existing classes (Schema=package.Class,…) |
modelNameMappings |
Mappings of schema names to model names (Schema=Model,…) |
nameMappings |
Mappings of property names to Java names (name=javaName,…) |
parameterNameMappings |
Mappings of parameter names to Java names (name=javaName,…) |
enumNameMappings |
Mappings of enum values to constant names (value=NAME,…) |
contentMediaTypeAsBinary |
Map strings with a non-JSON contentMediaType to binary types, like format: binary (on by default) |
useImplicitOneOfDiscriminator |
Dispatch oneOf schemas without a discriminator on a property whose value is constant in every member |
jsonAccessForReadWriteOnly |
Read readOnly properties from JSON only and write writeOnly ones only (@JsonProperty access) |
Verification
The codegen conformance suite runs this target on the Carpet Express OpenAPI fixture. Level 1 compares the output with its snapshots and checks each feature, Level 2 runs the language's type checker and linter, and Level 3 runs the generated code in contract tests against the fixture. All targets.
This target's support tier is Tier 1. It goes through all three levels before every release, with the goal of supporting every feature of the fixture. Its unsupported features are worked on first.
| Results | Level 1 | Level 2 | Level 3 |
|---|---|---|---|
| Release 0.12.0 | ✓ snapshots of 3.2, 3.1, 3.0, 2.0; 3.2: 45 supported, 0 not yet, 1 not checked | ✓ pass (openjdk version "21.0.13" 2026-10-20 LTS, Apache Maven 3.10.0) | ✓ 70 of 77 operations pass, 2 known failures (java) |
| Development version | ✓ snapshots of 3.2, 3.1, 3.0, 2.0; 3.2: 45 supported, 0 not yet, 1 not checked | runs before a release | runs before a release, 2 known failures |