client java

Generate a Java client of an OpenAPI document: a Maven project using Spring’s RestClient (the default) or RestTemplate, Spring Cloud OpenFeign interfaces, or Spring HTTP interfaces.

From an AsyncAPI document, the command generates a Java Kafka client library instead; see apigenie-generator client java (AsyncAPI).

Usage

apigenie-generator client java [...OPTIONS] INPUT_FILE

Description

The input must be an OpenAPI 3.0, 3.1 or 3.2 document. The generated project needs Java 17 and Maven; its dependencies come from Maven Central.

ApiClient client = new ApiClient();
client.setBearerToken("token");
PetsApi pets = new PetsApi(client);

List<Pet> page = pets.listPets(10, null);
ResponseEntity<Pet> response = pets.getPetWithHttpInfo(42L);
try (Stream<PetEvent> events = pets.watchPetsStream()) {
    events.limit(5).forEach(System.out::println);
}

--library selects how the client calls the API:

Library	Output
restclient (default)	ApiClient on Spring’s RestClient, one class per API
resttemplate	the same classes, with ApiClient on Spring’s RestTemplate
feign	Spring Cloud OpenFeign: @FeignClient interfaces extending Spring MVC interfaces, request interceptors of the security schemes
http-interface	Spring HTTP interfaces (@HttpExchange) and a configurator creating their proxies with a RestClient (or a WebClient with reactive)

The feign and http-interface libraries are the clients the spring-cloud and spring-http-interface libraries of apigenie-generator server spring generate, with the options of the client.

The rest of this section describes the restclient and resttemplate libraries. Their API classes are grouped by the first tag of operations (<Tag>Api); each operation has:

• op(...), returning the body of the response (void without content);
• opWithHttpInfo(...), returning the ResponseEntity, with the status and the headers;
• opStream(...) when the response can be streamed as text/event-stream, application/jsonl, application/x-ndjson or application/json-seq: a Stream of the items, typed by the itemSchema of the media type (x-itemSchema before 3.2) or the contentSchema of the data of events, read as they arrive. Closing the stream (try-with-resources) closes the connection.
• opWith<MediaType>(...) for each further request media type taking another Java type, e.g. updateShipmentWithJsonPatch(...) for application/json-patch+json.

Required parameters come first. Parameters are serialized with their style (form, spaceDelimited, pipeDelimited, deepObject, simple); parameters described with content are sent as JSON. Bodies are JSON, JSON Lines (a List of items), form fields, multipart parts (Spring Resources for files, JSON parts for objects, the content type of the encoding), text or binary (Resource). Binary responses are Resources. Methods other than the eight classic ones (QUERY, additionalOperations) are sent as they are; the JDK HttpClient the client uses allows them.

ApiClient holds:

• the servers of the document (setServerIndex, setServerVariables) or a base path (setBasePath); operations with servers of their own are sent to them, unless setOperationBasePath(operationId, url) says otherwise;
• one Authentication per security scheme, added to the operations requiring it: setBearerToken (HTTP bearer, OAuth 2 and OpenID Connect schemes, whose tokens are obtained elsewhere), setApiKey (headers, query parameters and cookies), setUsername and setPassword (HTTP basic);
• the ObjectMapper (createObjectMapper(): Java time, JsonNullable, absent properties left out, unknown properties ignored), default headers and cookies.

Responses with an error status raise an ApiException with the status, the headers and the body; application/problem+json responses raise a ProblemDetailsException with the RFC 9457 problem details, typed as the problem schema of the document.

Models are the Jackson classes of apigenie-generator server spring, without Swagger annotations:

• classes for objects, with the properties of allOf members (the properties of anyOf and oneOf alternatives are optional)
• interfaces for oneOf: with a discriminator, @JsonTypeInfo and @JsonSubTypes, its defaultMapping (x-defaultMapping before 3.2) as defaultImpl and the const values of the members as the names of implicit mappings; without one, the members are told apart by a property with constant values (useImplicitOneOfDiscriminator) or by their properties (useDeductionForOneOfInterfaces)
• enums, JsonNullable for nullable properties, Bean Validation annotations, java.time types
• readOnly properties only read from responses and writeOnly ones only sent (jsonAccessForReadWriteOnly)

x-internal operations and paths are left out.

The project contains pom.xml (Spring Framework, Jackson and Jakarta versions from the Spring Boot BOM, without Spring Boot), README.md, .openapi-generator-ignore and, in the base package, ApiClient, ApiException, ProblemDetailsException (with a problem schema), ServerConfiguration, ServerVariable, StreamDecoder (with streaming responses), RFC3339DateFormat, auth/ (Authentication, HttpBearerAuth, HttpBasicAuth, ApiKeyAuth), api/ and model/.

Not supported: callbacks and webhooks, OAuth 2 flows (tokens are set by hand), mutual TLS (set an SSLContext on the request factory of the RestClient.Builder or RestTemplate given to ApiClient), prefixItems (tuples are List<Object>), patternProperties, and constraints Bean Validation can’t express (multipleOf, conditional schemas). The feign library leaves out operations of methods other than the classic ones.

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 (feign, http-interface)
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
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-itemSchema	itemSchema of a media type in OpenAPI 3.0 and 3.1 documents: the type of the items of a streamed response
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 or its path item leaves the operation out
x-operation-extra-annotation	annotations of the method of an operation (feign)
x-version-param	true on a header or query parameter adds it to the headers or params of the @RequestMapping (feign)

The extensions can live in an overlay for this target instead of in the document, e.g. java.overlay.yaml:

overlay: 1.0.0
info:
  title: Java annotations
  version: 1.0.0
actions:
  - target: $.components.schemas.Pet
    update:
      x-class-extra-annotation: ['@com.acme.Audited']
      x-implements: [java.io.Serializable]
  - target: $.components.schemas.Pet.properties.name
    update:
      x-pattern-message: Lower-case letters only

apigenie-generator client java openapi.yaml --overlay java.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.client_java.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.).

-o, –output

Directory where the project is generated.

–package-name

Base package of the generated code, e.g. com.acme.pets; the api, model and configuration packages are derived from it unless set explicitly. Defaults to org.openapitools.client.

–package-version

Version of the Maven artifact. Defaults to the version of the API.

–library

restclient (default), resttemplate, feign or http-interface. Overrides the library of the configuration file.

-p, –property

An option of the “Configuration” section as name=value, e.g. -p useBeanValidation=false. Can be repeated; overrides the configuration file.

Configuration

version: '1.0'
commands:
  generate:
    client_java:
      library: restclient
      basePackage: com.acme.pets
      groupId: com.acme
      artifactId: pets-client
      useBeanValidation: true
      openApiNullable: true
      typeMappings:
        DateTime: java.time.Instant

The main options:

Option	Description
library	restclient (default), resttemplate, feign or http-interface
basePackage, apiPackage, modelPackage	Packages of the code (org.openapitools.client, .api, .model by default)
groupId, artifactId, artifactVersion	Coordinates of the Maven artifact (org.openapitools, openapi-java-client, the version of the API)
useSpringBoot4	The versions of Spring Boot 4 (Spring Framework 7) instead of Spring Boot 3.5
useBeanValidation	Bean Validation annotations on models (true by default)
openApiNullable	JsonNullable for nullable properties (true by default)
useTags	Group operations by tag (true by default) or by the first segment of their path
generateStreamMethods	Stream methods for streaming responses (true by default)
allHttpMethods	Operations of every HTTP method (true by default; false with feign)
contentMediaTypeAsBinary	Strings with a non-JSON contentMediaType are binary Resources (true by default)
useImplicitOneOfDiscriminator	Dispatch oneOf schemas on a property with constant values (true by default)
jsonAccessForReadWriteOnly	@JsonProperty(access) for readOnly and writeOnly properties (true by default)
typeMappings, importMappings, schemaMappings	Java types of OpenAPI types and schemas

All options:

Option	Description
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)
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
generationTimestamp	Timestamp used in @Generated annotations
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
interfaceOnly	Generate only API interfaces, without controllers
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
returnSuccessCode	Return the success code instead of 501 Not Implemented
unhandledException	Declare ‘throws Exception’ on API methods
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
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
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)
library	Client library: restclient (Spring RestClient, the default), resttemplate, feign (Spring Cloud OpenFeign) or http-interface (Spring HTTP interfaces)
allHttpMethods	Generate operations of every HTTP method (QUERY, COPY, …), not only the eight classic ones
generateStreamMethods	Generate Stream<T> methods for text/event-stream and application/jsonl responses

Unknown options are errors.