Skip to content

Maven OpenAPI Generator Setup

Tool: OpenAPI Generator Maven Plugin Input: AnkaSecureAPI.json Output: co.ankatech.secure.client. (auto-generated) Library:* okhttp-gson

This page describes how we automatically generate the classes under co.ankatech.secure.client.* (APIs, models, and the ApiClient) using the OpenAPI Generator Maven Plugin. These classes are then consumed by AnkaSecureOpenApiClient and the rest of the AnkaSecure SDK.

Build Configuration - Not Implementation Code

This page contains Maven XML configuration showing how to generate OpenAPI client code. This is:

  • Build configuration: pom.xml plugin setup
  • Code generation: Automated from OpenAPI specification
  • Not implementation code: Build automation, not runtime logic

Developers modifying the API specification or build process may refer to this guide.

1. Introduction

OpenAPI Generator allows you to turn an OpenAPI/Swagger specification (e.g., AnkaSecureAPI.json) into a complete Java client library. The Maven plugin automates this step during the build, ensuring your generated code stays in sync with the API spec.

Key concepts:

  • inputSpec: The path to your OpenAPI specification file (.json or .yaml).

  • generatorName: The target language/framework (here, java).

  • apiPackage, modelPackage, invokerPackage: Packages for the generated APIs, models, and supporting code.

  • library: Specifies the HTTP library to use (here, okhttp-gson).

2. Plugin Configuration

Below is an excerpt from the pom.xml that configures the plugin:

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>${openapi.generator.version}</version>
    <executions>
        <execution>
            <id>generate-client</id>
            <phase>generate-sources</phase>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <!-- Location of the API spec: -->
                <inputSpec>${project.basedir}/AnkaSecureAPI.json</inputSpec>

                <!-- We generate Java code using the OkHttp + Gson library: -->
                <generatorName>java</generatorName>
                <library>okhttp-gson</library>

                <!-- Output folder for generated sources: -->
                <output>${project.build.directory}/generated-sources/openapi</output>

                <!-- Package definitions: -->
                <apiPackage>co.ankatech.secure.client.api</apiPackage>
                <modelPackage>co.ankatech.secure.client.model</modelPackage>
                <invokerPackage>co.ankatech.secure.client.invoker</invokerPackage>

                <!-- Additional configuration options: -->
                <configOptions>
                    <dateLibrary>java8</dateLibrary>
                    <hideGenerationTimestamp>true</hideGenerationTimestamp>
                    <useJakartaEe>true</useJakartaEe>
                    <gsonFire>false</gsonFire>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

Key Elements

  • <phase>generate-sources</phase>

    Ensures generation runs at the correct build phase. The newly generated code becomes part of the compilation path.

  • <inputSpec>

    Points to the local OpenAPI file. Whenever AnkaSecureAPI.json is updated, re-running mvn compile (or the corresponding phase) regenerates the client code.

  • <output>

    The generated Java code is stored in target/generated-sources/openapi. Usually, you add this directory to the Maven source folders so it gets compiled with the rest of the code.

  • apiPackage / modelPackage / invokerPackage

    Controls how packages are laid out. For example, co.ankatech.secure.client.api will contain the API interfaces like AuthenticationApi, KeyManagementApi, etc.

  • <library>okhttp-gson</library>

    Tells the generator to use OkHttp + Gson as the underlying HTTP and JSON libraries.

  • <dateLibrary>java8</dateLibrary>

    Ensures date/time types use java.time.* classes.

  • <useJakartaEe>true</useJakartaEe>

    Generates code with jakarta.* packages instead of the older javax.*.

3. Integration with Project

The generated code integrates seamlessly with the AnkaSecure project:

Step 1: Generate

Maven runs the plugin during the generate-sources phase:

mvn generate-sources

Generated files appear in: target/generated-sources/openapi/

Step 2: Compile

The generated sources are automatically added to the compilation classpath. Maven compiles them along with the rest of the project code.

Step 3: Use

Classes become available for import:

import co.ankatech.secure.client.invoker.ApiClient;
import co.ankatech.secure.client.api.KeyManagementApi;
import co.ankatech.secure.client.model.GenerateKeyRequest;

Step 4: Extend

Our custom AnkaSecureOpenApiClient wraps these generated classes to implement:

  • Authentication management
  • Token caching
  • Streaming support
  • Progress bars
  • PQC transport layer

4. Tips & Best Practices

Version Control

Generated code in version control:

  • ❌ Not recommended: Commit generated code to git
  • ✅ Recommended: Add target/generated-sources/ to .gitignore
  • ✅ Rely on plugin: Generate at build time for consistency

Rationale: Generated code changes with every API spec update. Keeping it out of version control reduces merge conflicts and keeps diffs clean.

Regeneration Workflow

When the OpenAPI specification changes:

# Step 1: Update API specification
# Edit: AnkaSecureAPI.json

# Step 2: Clean previous generated code
mvn clean

# Step 3: Regenerate client code
mvn generate-sources

# Step 4: Compile and verify
mvn compile

# Step 5: Test
mvn test

Automatic: The plugin runs automatically during mvn compile or mvn package.

Customization Options

The OpenAPI Generator plugin supports extensive customization:

Additional config options:

<configOptions>
    <dateLibrary>java8</dateLibrary>
    <hideGenerationTimestamp>true</hideGenerationTimestamp>
    <useJakartaEe>true</useJakartaEe>
    <gsonFire>false</gsonFire>
    <serializableModel>true</serializableModel>
    <performBeanValidation>true</performBeanValidation>
    <useBeanValidation>true</useBeanValidation>
</configOptions>

Custom templates:

Override default code generation templates for fine-grained control over generated code structure.

See OpenAPI Generator documentation for complete customization options.

OpenAPI Generator

Official Documentation:

AnkaSecure Documentation

Build & Architecture:

SDK & API:

  • SDK Overview - SDK wrapping the OpenAPI client
  • Core API Overview* - REST API specification
  • Core API Endpoints* - HTTP endpoint reference

Last Updated: December 2025
Plugin Version: 7.x OpenAPI Spec Version: 3.0.x

© 2025 ANKATech Solutions Inc. All rights reserved.

* restricted content — see higher-tier documentation