adarro / quarkus-openapi-generator

OpenApi Generator - REST Client Generator

Quarkus - OpenAPI Generator

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

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.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.

Known Limitations

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

• No authentication support (Basic, Bearer, OAuth2)
• 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 ❤️

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Ricardo Zanini 💻 🚧

Helber Belmiro 📖

George Gastaldi 💻 🚇

Rishi Kumar Ray 🚇

This project follows the all-contributors specification. Contributions of any kind welcome!