MetaEngine OpenAPI Java Spring

Generate Java Spring services and models from OpenAPI/Swagger specifications.

A Maven plugin that produces typed Spring RestClient service clients and model classes from an OpenAPI spec, with built-in authentication, retries, timeouts, and error handling — straight into your build at generate-sources.

---

Quick Links

• Maven Central: eu.metaengine:metaengine-openapi-java-spring-maven-plugin
• NuGet Package: MetaEngine.Java.OpenApi.Spring
• Website: metaengine.eu

---

Features

• ✅ Spring RestClient - Typed service clients with base-URL injection via a Spring property
• ✅ Authentication - Bearer token, basic auth, and custom headers from environment variables
• ✅ Retries - Exponential-backoff retries with a configurable max attempt count
• ✅ Timeouts - Single timeout, or split connect / read timeouts
• ✅ Error Handling - Smart error handling on the RestClient
• ✅ JavaDoc - Optional doc-comment generation from OpenAPI descriptions and examples
• ✅ Tag Filtering - Generate only the operations you need
• ✅ Options Object - Collapse long parameter lists into an options object past a threshold

---

Requirements

• JDK 11 or later
• Maven 3.6 or later
• .NET 8.0 runtime (Download) — the plugin runs the bundled MetaEngine generator via dotnet, so the runtime must be on your PATH

---

Quick Start

Add the plugin to your pom.xml and bind it to the generate-sources phase:

<build>
  <plugins>
    <plugin>
      <groupId>eu.metaengine</groupId>
      <artifactId>metaengine-openapi-java-spring-maven-plugin</artifactId>
      <version>1.0.0</version>
      <executions>
        <execution>
          <goals><goal>generate</goal></goals>
          <configuration>
            <inputSpec>src/main/resources/openapi.json</inputSpec>
            <packageName>com.example.api</packageName>
            <documentation>true</documentation>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Then generate (the output is added to your compile source roots automatically):

mvn generate-sources

The plugin can also be run directly without a lifecycle binding:

mvn eu.metaengine:metaengine-openapi-java-spring-maven-plugin:generate \
  -Dmetaengine.inputSpec=src/main/resources/openapi.json \
  -Dmetaengine.packageName=com.example.api

---

Configuration Options

Every option is a <configuration> element, also settable on the command line via its metaengine.* property.

Element	Property	Description	Default
inputSpec (required)	metaengine.inputSpec	OpenAPI spec file path or URL	-
packageName (required)	metaengine.packageName	Java package for generated code	-
outputDirectory	metaengine.outputDirectory	Output directory	${project.build.directory}/generated-sources/metaengine
includeTags	metaengine.includeTags	Only generate operations with these tags (comma-separated)	-
baseUrlProperty	metaengine.baseUrlProperty	Spring property name for base-URL injection	api.base-url
documentation	metaengine.documentation	Generate JavaDoc comments	false
bearerAuth	metaengine.bearerAuth	Env var name holding the bearer token	-
bearerAuthHeader	metaengine.bearerAuthHeader	Custom header name for bearer auth	Authorization
basicAuth	metaengine.basicAuth	Env var names for basic auth (USER_VAR,PASS_VAR)	-
customHeaders	metaengine.customHeaders	Custom headers from env vars (Header-Name:ENV_VAR, repeatable)	-
timeout	metaengine.timeout	Request timeout in seconds (connect + read)	-
timeoutConnect	metaengine.timeoutConnect	Connect timeout in seconds	-
timeoutRead	metaengine.timeoutRead	Read timeout in seconds	-
retry	metaengine.retry	Enable retries with exponential backoff (max attempts)	3 when enabled
errorHandling	metaengine.errorHandling	Enable smart error handling on the RestClient	false
optionsThreshold	metaengine.optionsThreshold	Parameter count that triggers the options-object pattern	4
strictValidation	metaengine.strictValidation	Enable strict OpenAPI validation	false
clean	metaengine.clean	Clean the output directory before generation	false
verbose	metaengine.verbose	Enable verbose logging	false

---

Production-Ready Configuration

<configuration>
  <inputSpec>src/main/resources/openapi.json</inputSpec>
  <packageName>com.example.api</packageName>
  <documentation>true</documentation>

  <!-- Auth from environment variables -->
  <bearerAuth>API_TOKEN</bearerAuth>

  <!-- Resilience -->
  <timeout>30</timeout>
  <retry>3</retry>
  <errorHandling>true</errorHandling>

  <!-- Generate only what you need -->
  <includeTags>pets,store</includeTags>
</configuration>

Authentication values are read from environment variables at runtime — secrets never end up in your generated source or your pom.xml.

---

Generated Code Structure

target/generated-sources/metaengine/
  └── com/example/api/
      ├── model/          # One file per schema (POJOs)
      │   ├── Pet.java
      │   ├── Category.java
      │   └── ...
      └── service/        # One Spring service per tag (RestClient-based)
          ├── PetsService.java
          └── StoreService.java

Services are Spring components — inject them directly into your beans. The base URL is bound to the baseUrlProperty (default api.base-url) from your Spring configuration.

---

Support

• Issues: GitHub Issues
• Email: info@metaengine.eu
• Website: metaengine.eu

---

License

MIT License - see LICENSE file for details.

---

About This Repository

This is the documentation and issue tracking repository for MetaEngine OpenAPI Java Spring. The plugin is published to Maven Central.

Source code is proprietary, but the plugin is free to use under the MIT license.