Akka OpenAPI Maven Plugin

Generate OpenAPI 3.1 specifications from Akka SDK HTTP endpoint annotations at compile time.

Features

• Zero Configuration - Works out-of-the-box with sensible defaults
• Compile-Time Generation - No runtime overhead, perfect for serverless/containers
• OpenAPI 3.1 - Latest specification with full JSON Schema support
• Automatic Schema Generation - POJOs converted to JSON schemas automatically
• JavaDoc Extraction - Uses your existing documentation for descriptions
• Validation - Ensures generated specs are valid before writing

Quick Start

Add the plugin to your pom.xml:

<build>
    <plugins>
        <plugin>
            <groupId>sh.oso</groupId>
            <artifactId>akka-openapi-maven-plugin</artifactId>
            <version>1.0.0-SNAPSHOT</version>
            <executions>
                <execution>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Run:

mvn compile

Your OpenAPI specification will be generated at target/openapi.yaml.

Example

Given an Akka SDK endpoint:

/**
 * Customer management endpoint.
 */
@HttpEndpoint("/customers")
public class CustomerEndpoint {

    /**
     * Get a customer by ID.
     * @param id the customer unique identifier
     * @return the customer or 404 if not found
     */
    @Get("/{id}")
    public Customer getCustomer(String id) {
        // ...
    }

    /**
     * Create a new customer.
     */
    @Post
    public Customer createCustomer(CreateCustomerRequest request) {
        // ...
    }
}

The plugin generates:

openapi: 3.1.0
info:
  title: My API
  version: 1.0.0
paths:
  /customers/{id}:
    get:
      summary: Get a customer by ID.
      operationId: getCustomer
      parameters:
        - name: id
          in: path
          required: true
          description: the customer unique identifier
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '404':
          description: Not Found
  /customers:
    post:
      summary: Create a new customer.
      operationId: createCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
components:
  schemas:
    Customer:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
    CreateCustomerRequest:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
        email:
          type: string
          format: email

Configuration

<plugin>
    <groupId>sh.oso</groupId>
    <artifactId>akka-openapi-maven-plugin</artifactId>
    <version>1.0.0</version>
    <configuration>
        <!-- Output settings -->
        <outputFile>${project.build.directory}/openapi.yaml</outputFile>
        <outputFormat>yaml</outputFormat> <!-- yaml or json -->

        <!-- API metadata -->
        <apiTitle>${project.name}</apiTitle>
        <apiVersion>${project.version}</apiVersion>
        <apiDescription>${project.description}</apiDescription>

        <!-- Package scanning -->
        <scanPackages>
            <package>com.example.endpoints</package>
        </scanPackages>

        <!-- Server definitions -->
        <servers>
            <server>
                <url>https://api.example.com</url>
                <description>Production</description>
            </server>
        </servers>

        <!-- Validation -->
        <failOnValidationError>true</failOnValidationError>

        <!-- Skip generation -->
        <skip>false</skip>
    </configuration>
</plugin>

Supported Akka SDK Annotations

Annotation	OpenAPI Mapping
@HttpEndpoint(path)	Base path for all operations
@Get, @Post, @Put, @Delete, @Patch	HTTP methods
Path parameters (e.g., /{id})	parameters[in=path]
Last complex type parameter	requestBody
Method return type	Response schema
JavaDoc comments	summary and description

Custom Annotations

For additional control, use the optional custom annotations:

@HttpEndpoint("/customers")
@OpenAPITag(name = "Customers", description = "Customer management")
public class CustomerEndpoint {

    @Get("/{id}")
    @OpenAPIResponse(status = "200", description = "Customer found")
    @OpenAPIResponse(status = "404", description = "Customer not found")
    public Customer getCustomer(String id) {
        // ...
    }
}

Low-Level HttpResponse Return Types

When an endpoint returns a domain object directly, the plugin infers the response schema from the method return type:

@Get("/{customerId}")
public CustomerResponse getCustomer(String customerId) {
    return service.getCustomer(customerId);
}

The same inference works for asynchronous methods such as CompletionStage<CustomerResponse>.

For low-level Akka responses, endpoint methods return akka.http.javadsl.model.HttpResponse. That type does not carry the response body type in the Java signature, even when the implementation uses HttpResponses.ok(payload), so annotate the method with @OpenAPIResponseSchema:

@Get("/{customerId}")
@OpenAPIResponseSchema(CustomerResponse.class)
public HttpResponse getCustomer(String customerId) {
    return HttpResponses.ok(service.getCustomer(customerId));
}

This also works for asynchronous low-level responses:

@Get("/{customerId}")
@OpenAPIResponseSchema(CustomerResponse.class)
public CompletionStage<HttpResponse> getCustomer(String customerId) {
    return service.getCustomer(customerId)
        .thenApply(HttpResponses::ok);
}

Both low-level examples produce:

responses:
  "200":
    description: Success
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/CustomerResponse"

Note: If a method returns HttpResponse or CompletionStage<HttpResponse> without @OpenAPIResponseSchema, the generated response will have no content schema. The plugin logs a warning in this case.

Documentation

• Getting Started
• Configuration Reference
• Examples
• Troubleshooting

Requirements

• Java 17 or later
• Maven 3.6.3 or later
• Akka SDK 3.0.0 or later. The repository tracks Akka SDK 3.5.17 as the current reference version.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

• Akka SDK - The Akka platform for building reactive applications
• Swagger Core - OpenAPI implementation for Java
• ClassGraph - Fast classpath scanner