# apigenie-generator server spring

Source: https://apigenie.pl/docs/reference/generator/server-spring
Part of the reference of [apigenie-generator](https://apigenie.pl/docs/reference/generator.md).
Its other pages: [Conformance results](https://apigenie.pl/docs/reference/generator/conformance.md), [docs](https://apigenie.pl/docs/reference/generator/docs.md), [data](https://apigenie.pl/docs/reference/generator/data.md), [schema zod](https://apigenie.pl/docs/reference/generator/schema-zod.md), [client csharp](https://apigenie.pl/docs/reference/generator/client-csharp.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir.md), [client fetch](https://apigenie.pl/docs/reference/generator/client-fetch.md), [client go](https://apigenie.pl/docs/reference/generator/client-go.md), [client java](https://apigenie.pl/docs/reference/generator/client-java.md), [client python](https://apigenie.pl/docs/reference/generator/client-python.md), [client rust](https://apigenie.pl/docs/reference/generator/client-rust.md), [client swift](https://apigenie.pl/docs/reference/generator/client-swift.md), [server aspnet](https://apigenie.pl/docs/reference/generator/server-aspnet.md), [server axum](https://apigenie.pl/docs/reference/generator/server-axum.md), [server express](https://apigenie.pl/docs/reference/generator/server-express.md), [server fastapi](https://apigenie.pl/docs/reference/generator/server-fastapi.md), [server go](https://apigenie.pl/docs/reference/generator/server-go.md), [server hummingbird](https://apigenie.pl/docs/reference/generator/server-hummingbird.md), [server mcp](https://apigenie.pl/docs/reference/generator/server-mcp.md), [server orpc](https://apigenie.pl/docs/reference/generator/server-orpc.md), [server phoenix](https://apigenie.pl/docs/reference/generator/server-phoenix.md), [server vapor](https://apigenie.pl/docs/reference/generator/server-vapor.md), [client csharp](https://apigenie.pl/docs/reference/generator/client-csharp-asyncapi.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir-asyncapi.md), [client go](https://apigenie.pl/docs/reference/generator/client-go-asyncapi.md), [client java](https://apigenie.pl/docs/reference/generator/client-java-asyncapi.md), [client kafkajs](https://apigenie.pl/docs/reference/generator/client-kafkajs.md), [client python](https://apigenie.pl/docs/reference/generator/client-python-asyncapi.md), [client ws](https://apigenie.pl/docs/reference/generator/client-ws.md), [server aspnet](https://apigenie.pl/docs/reference/generator/server-aspnet-asyncapi.md), [server faststream](https://apigenie.pl/docs/reference/generator/server-faststream.md), [server go](https://apigenie.pl/docs/reference/generator/server-go-asyncapi.md), [server kafkajs](https://apigenie.pl/docs/reference/generator/server-kafkajs.md), [server phoenix](https://apigenie.pl/docs/reference/generator/server-phoenix-asyncapi.md), [server spring](https://apigenie.pl/docs/reference/generator/server-spring-asyncapi.md), [server ws](https://apigenie.pl/docs/reference/generator/server-ws.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir-protobuf.md), [server elixir-grpc](https://apigenie.pl/docs/reference/generator/server-elixir-grpc.md), [server absinthe](https://apigenie.pl/docs/reference/generator/server-absinthe.md).

[Tier 1](/docs/reference/generator/conformance#tiers) · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · [Verification](#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)](/docs/reference/generator/server-spring-asyncapi).

## Usage

```sh
apigenie-generator server spring [...OPTIONS] INPUT_FILE
```

## Description

The generator produces the same code as the `spring` generator of
[openapi-generator](https://openapi-generator.tech), 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](/docs/reference/generator#swagger-20-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 Maven `pom.xml`
- `spring-cloud`: Feign clients (`PetApiClient`) and their security configuration
- `spring-http-interface`: `@HttpExchange` interfaces and a configurator creating their proxies

The `spring-cloud` and `spring-http-interface` clients are generated by the writers of
[`apigenie-generator client java`](/docs/reference/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.xml` and `README.md`
- the application class, `RFC3339DateFormat`, `application.properties` and a copy of the OpenAPI
  document in `src/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`, `hashCode` and `toString`, enums, interfaces for
  `oneOf` schemas, and class hierarchies for `allOf` schemas 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:

- `useSpringBoot3` is `true` by default
- generated files are marked with `@Generated(value = "API Genie")`
- `@Generated` has no `date` unless `hideGenerationTimestamp` is `false` (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
  `@JsonSubTypes` for their `x-discriminator-value`, where openapi-generator writes a parent
  class that they extend
- schemas whose names give the same class name (e.g. `app-permissions` and an inline
  `app_permissions`) get classes with numeric suffixes, e.g. `AppPermissions1`

Since 0.12.0, the generator also covers:

- callbacks, as `@Callback` annotations on the operations that register them, and webhooks, as an
  `ApiWebhooks` interface annotated with `@Webhooks` (both need `annotationLibrary: swagger2`, the
  default with SpringDoc; `apiFirst` leaves out `ApiWebhooks`). They document the requests the
  server sends. The generator writes no code that sends them. The SpringDoc versions in the
  generated `pom.xml` (2.6.0, or 1.6.14 for Spring Boot 2) don't read `@Webhooks`
- `deepObject` query 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 with `useBeanValidation` when 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 a
  `Flux` of their items; Spring MVC writes server-sent events and `application/x-ndjson` item by
  item, and `application/jsonl`, `application/x-jsonlines` and `application/json-seq` once the
  `Flux` completes
- strings with a non-JSON `contentMediaType` and no `contentEncoding` as files and binary bodies,
  as with `format: binary` (`contentMediaTypeAsBinary`, on by default)
- the flows of OAuth 2 schemes and `mutualTLS` schemes in the SpringDoc configuration
- `writeOnly` properties, documented with `Schema.AccessMode.WRITE_ONLY`
- tuples, `patternProperties`, `multipleOf` (a generated `MultipleOf` constraint) and conditional
  schemas (`@AssertTrue` methods), modelled as in
  [`apigenie-generator client java`](/docs/reference/generator/client-java); the `MultipleOf`
  constraint and the `@AssertTrue` methods need `useBeanValidation`

Limitations:

- `deepObject` parameters of other types are read as plain query parameters.
- Streaming responses whose `schema` isn't an array are returned as plain bodies. A response
  whose first media type has only an `itemSchema` gets no body (a `Void` return type).
- Server-sent events carry each item as their `data`, without `event` or `id`.
- With `reactive`, WebFlux writes server-sent events and `application/x-ndjson`; the generator
  adds no encoder of `application/jsonl`, `application/x-jsonlines` or `application/json-seq`.
- A JSON Lines or JSON sequence request body with an array `schema` is a `List` that no generated
  converter reads. With only an `itemSchema`, the method takes the type of the body's first media
  type, and has no body parameter when that media type has no `schema` either.
- Strings with a `contentEncoding` stay `String`.
- 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`:

```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']
```

```sh
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](/docs/reference/generator#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)](/docs/reference/generator/server-spring-asyncapi#configuration)):

```yaml
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&lt;T&gt; |
| `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](/docs/reference/generator#conformance-checks) 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](/docs/reference/generator/conformance#openapi).

This target's support tier is [Tier 1](/docs/reference/generator/conformance#tiers). 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 |
