Quarkus - OpenAPI Generator

Quarkus' extension for generation of Rest Clients based on OpenAPI specification files.

This extension is based on the OpenAPI Generator Tool.

Getting Started

Add the following dependency to your project's pom.xml file:

<dependency>
  <groupId>io.quarkiverse.openapi.generator</groupId>
  <artifactId>quarkus-openapi-generator</artifactId>
  <version>0.1.0</version>
</dependency>

You will also need to add or update the quarkus-maven-plugin configuration with the following:

⚠️ You probably already have this configuration if you created your application with the Quarkus Starter. That said, double-check your configuration not to add another plugin entry.

<plugin>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-maven-plugin</artifactId>
  <extensions>true</extensions>
  <executions>
    <execution>
      <goals>
        <goal>build</goal>
        <goal>generate-code</goal>
        <goal>generate-code-tests</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Now, create the directory openapi under your src/main/ path and add the OpenAPI spec files there. We support JSON, YAML and YML extensions.

To fine tune the configuration for each spec file, add the following entry to your properties file. In this example, our spec file is in src/main/openapi/petstore.json:

quarkus.openapi-generator.codegen.spec."petstore.json".base-package=org.acme.openapi

Note that the file name is used to configure the specific information for each spec.

Run mvn compile to generate your classes in target/generated-sources/open-api-json path:

- org.acme.openapi
  - api
    - PetApi.java
    - StoreApi.java
    - UserApi.java
  - model
    - Address.java
    - Category.java
    - Customer.java
    - ModelApiResponse.java
    - Order.java
    - Pet.java
    - Tag.java
    - User.java

You can reference the generated code in your project, for example:

import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

import org.acme.openapi.api.PetApi;
import org.eclipse.microprofile.rest.client.inject.RestClient;
import org.jboss.resteasy.annotations.jaxrs.PathParam;

@Produces(MediaType.APPLICATION_JSON)
@Path("/petstore")
public class PetResource {

    @RestClient
    @Inject
    PetApi petApi;
}

See the integration-tests module for more information of how to use this extension. Please be advised that the extension is on experimental, early development stage.

Authentication Support

If your OpenAPI specification file has securitySchemes definitions, the inner generator will register ClientRequestFilters providers for you to implement the given authentication mechanism.

To provide the credentials for your application, you can use the Quarkus configuration support. The configuration key is composed using this pattern: [base_package].security.auth.[security_scheme_name]/[auth_property_name]. Where:

base_package is the package name you gave when configuring the code generation using quarkus.openapi-generator.codegen.spec.[open_api_file].base-package property.
security_scheme_name is the name of the security scheme object definition in the OpenAPI file. Given the following excerpt, we have api_key and basic_auth security schemes:

{
  "securitySchemes": {
    "api_key": {
      "type": "apiKey",
      "name": "api_key",
      "in": "header"
    },
    "basic_auth": {
      "type": "http",
      "scheme": "basic"
    }
  }
}

auth_property_name varies depending on the authentication provider. For example, for Basic Authentication we have username and password. See the following sections for more details.

Tip: on production environments you will likely to use HashiCorp Vault or Kubernetes Secrets to provide this information for your application.

Basic HTTP Authentication

For Basic HTTP Authentication, these are the supported configurations:

Description	Property Key	Example
Username credentials	`[base_package].security.auth.[security_scheme_name]/username`	`org.acme.openapi.security.auth.basic_auth/username`
Password credentials	`[base_package].security.auth.[security_scheme_name]/password`	`org.acme.openapi.security.auth.basic_auth/password`

Bearer Token Authentication

For Bearer Token Authentication, these are the supported configurations:

Description	Property Key	Example
Bearer Token	`[base_package].security.auth.[security_scheme_name]/bearer-token`	`org.acme.openapi.security.auth.bearer/bearer-token`

API Key Authentication

Similarly to bearer token, the API Key Authentication also has the token entry key property:

Description	Property Key	Example
API Key	`[base_package].security.auth.[security_scheme_name]/api-key`	`org.acme.openapi.security.auth.apikey/api-key`

The API Key scheme has an additional property that requires where to add the API key in the request token: header, cookie or query. The inner provider takes care of that for you.

Known Limitations

These are the known limitations of this pre-release version:

No OAuth2 support
No reactive support
Only Jackson support

We will work in the next few releases to address these use cases, until there please provide feedback for the current state of this extension. We also love contributions ❤️