Maven Central NuGet v1.0.1 MIT

OpenAPI to Java Spring Client Generator

eu.metaengine:metaengine-openapi-java-spring-maven-plugin

Convert OpenAPI 3.x to Java Spring services and models, delivered as a Maven plugin. Typed RestClient services with bearer/basic auth, retries, timeouts, and error handling — generated straight into your build at generate-sources.

OpenAPI 3.xMetaEngine IRJava · Spring
Open the browser UI for hosted OpenAPI to Java Spring generation
Install

Pick your registry

The same generator, published to every ecosystem we support. Install however your project expects.

Maven CentralPrimaryeu.metaengine:metaengine-openapi-java-spring-maven-plugin
$eu.metaengine:metaengine-openapi-java-spring-maven-plugin
v1.0.1
NuGetMetaEngine.Java.OpenApi.Spring
$dotnet add package MetaEngine.Java.OpenApi.Spring
v1.0.0
Usage

Drive it from Maven or programmatically

Maven Central ships a build-time plugin that runs inside your build. NuGet ships the same generator as a C# fluent API — same options, same output.

Maven Central · build-time plugin

Add the plugin to your pom.xml. Its generate goal binds to the generate-sources phase, so the Spring client and models are produced — and added to your compile roots — on every mvn compile or package. Point <inputSpec> at a spec file or URL and set the target <packageName>.

Plugin setup
pom.xml
<build>
  <plugins>
    <plugin>
      <groupId>eu.metaengine</groupId>
      <artifactId>metaengine-openapi-java-spring-maven-plugin</artifactId>
      <version>1.0.1</version>
      <executions>
        <execution>
          <id>generate-api-client</id>
          <goals>
            <goal>generate</goal>
          </goals>
          <configuration>
            <inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
            <packageName>com.example.api</packageName>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

The generate goal binds to the generate-sources phase, so a normal mvn compile (or package) produces the client and registers it as a compile source root — no extra wiring. <inputSpec> accepts a local path or an http(s) URL; OpenAPI 3.0 and 3.1 in JSON or YAML.

Configuration examples
Auth, retries and a request timeout
<configuration>
  <inputSpec>${project.basedir}/openapi.yaml</inputSpec>
  <packageName>com.example.api</packageName>
  <bearerAuth>API_TOKEN</bearerAuth>
  <timeout>30</timeout>
  <retry>3</retry>
  <errorHandling>true</errorHandling>
</configuration>
Tag filtering, JavaDoc and a custom base-url property
<configuration>
  <inputSpec>https://api.example.com/openapi.json</inputSpec>
  <packageName>com.example.api</packageName>
  <includeTags>payments,refunds</includeTags>
  <baseUrlProperty>api.base-url</baseUrlProperty>
  <documentation>true</documentation>
</configuration>
Basic auth and a tenant header from env vars
<configuration>
  <inputSpec>${project.basedir}/openapi.yaml</inputSpec>
  <packageName>com.example.api</packageName>
  <basicAuth>API_USER,API_PASS</basicAuth>
  <customHeaders>
    <customHeader>X-Tenant-ID:TENANT_ID</customHeader>
  </customHeaders>
</configuration>
Configuration
Element
Description
<inputSpec>
OpenAPI spec — local file path or http(s) URL. Required.
<packageName>
Java package for the generated code, e.g. com.example.api. Required.
<outputDirectory>
Output directory [default: ${project.build.directory}/generated-sources/metaengine]. Added to the compile source roots.
<includeTags>
Only generate operations carrying these tags (comma-separated)
<baseUrlProperty>
Spring property name for base-URL injection [default: api.base-url]
<documentation>
Generate JavaDoc comments [default: false]
<bearerAuth>
Env var holding the bearer token — adds an Authorization header to every request
<bearerAuthHeader>
Custom header name for the bearer token [default: Authorization]. Requires bearerAuth.
<basicAuth>
HTTP Basic auth from env vars, format USER_VAR,PASS_VAR
<customHeaders>
Static headers from env vars (Header-Name:ENV_VAR) as <customHeader> children. Repeatable.
<timeout>
Request timeout in seconds (connect + read)
<timeoutConnect>
Connect timeout in seconds
<timeoutRead>
Read timeout in seconds
<retry>
Enable retries with exponential backoff [default attempts: 3]
<errorHandling>
Smart error handling on RestClient — status-aware null / error / throw [default: false]
<optionsThreshold>
Parameter count threshold for the options-object pattern [default: 4]
<strictValidation>
Enable strict OpenAPI validation [default: false]
<clean>
Clean the output directory before generation (remove files not in generation) [default: false]
<verbose>
Enable verbose logging [default: false]
Options reference

Every knob, documented

Every option is available on the C# fluent API as a method; the Maven plugin exposes most as <configuration> elements. Cross-cutting auth, headers, retries and timeouts apply across frameworks.

Spring Options

3
  • WithBaseUrlProperty(string)Spring property placeholder for base-URL injection (default: "api.base-url"). Generated services bind it with @Value("${...}").
  • WithBeanValidation()Emit Jakarta Bean Validation annotations (@NotNull, @Min / @Max, @Size, @Pattern, @Email) on model records from schema constraints
  • WithNonNullSerialization()Add @JsonInclude(NON_NULL) to records so unset nullable fields drop out of the serialized JSON

Auth · Headers · Resilience

13
  • WithErrorHandling()Smart error handling on RestClient based on HTTP status (404 / 403 → null · 400 / 422 / 409 → error body · 401 / 5xx → throw)
  • WithErrorHandling(errors => errors...)Per-status routing: ReturnNullFor(404, 403) · ReturnErrorFor(400, 422) · ThrowFor(401, 500)
  • WithBearerAuth()Bearer token from env var (default API_TOKEN) — adds Authorization header
  • WithBearerAuth(string)Bearer token from a specific env var name
  • WithBearerAuth(string, string)Bearer token with custom header name (e.g. X-Api-Key)
  • WithBasicAuth()HTTP Basic auth from default env vars (API_USERNAME / API_PASSWORD)
  • WithBasicAuth(string, string)HTTP Basic auth from username + password env vars
  • WithCustomHeader(string, string)Static header from env var. Repeatable (e.g. X-Tenant-ID ← TENANT_ID)
  • WithTimeout(double)Request timeout in seconds for all operations
  • WithTimeout(double?, double?, double?, double?)Granular timeout: connect · read · write · pool
  • WithRetries()Retries with exponential backoff (default status 429, 503)
  • WithRetries(int)Retries with custom max attempts
  • WithRetries(int, double, double, int[])Retries with full custom settings including status codes

Java Options

3
  • WithDocumentation()Generate JavaDoc comments on methods and parameters from the spec
  • WithMethodNames(Func)Custom method naming rule
  • WithOptionsObjectThreshold(int)Parameter count for options object (default: 4)

OpenAPI Filtering

3
  • WithStrictValidation()Enable strict OpenAPI validation
  • WithOperationFilter(Func)Filter operations by predicate
  • WithHeaderFilter(Func)Filter header parameters

Naming Transformations

3
  • Types(Func)Transform type names
  • Paths(Func)Transform output paths
  • FileNames(Func)Transform file names

File Management

5
  • CleanDestination()Clean output directory before generation
  • AlwaysOverwrite()Always overwrite existing files
  • OnlyWhenModelChanged()Update only when model changes
  • OnlyWhenNew()Write only new files, preserve existing
  • CleanDirectories(...)Clean specific subdirectories

Diagnostics

2
  • Verbose()Enable verbose logging
  • WithLogger(Action<string>)Route generation log output to a custom sink
Features

Why this package is different

Records & sealed types
Immutable Java records for DTOs and sealed interfaces for polymorphic payloads — exhaustive switch over the hierarchy.
Spring-native
RestClient services with constructor injection and configurable base-URL properties. Drops into a Spring Boot 3 app as-is.
Jackson-correct
NON_NULL serialization and Bean Validation annotations generated straight from the spec constraints.
Deterministic output
Same spec + same options produce byte-identical files. Safe to commit, safe to diff in review, safe to cache in CI.
Flexible naming
Case conventions are configurable per role — types, properties, operations, enums. Idiomatic in the target by default.
Semver-honest
Spec diff drives the version bump. Additive changes = minor, removed operations = major. Never a surprise in your lockfile.