Quarkus - OpenAPI Generator - Server

Quarkus' extension for generation of server Stubs based on OpenAPI specification files.

This extension is based on the Apicurio Codegen tool.

This extension is for REST code generation for server side only.

Want to contribute? Great! We try to make it easy, and all contributions, even the smaller ones, are more than welcome. This includes bug reports, fixes, documentation, examples… But first, read this page.

Getting Started

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

<dependency>
  <groupId>io.quarkiverse.openapi.generator</groupId>
  <artifactId>quarkus-openapi-generator-server</artifactId>
  <version>3.0.0-SNAPSHOT</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 Code Quarkus. 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/resources path and add the OpenAPI spec files there. We support JSON, YAML and YML extensions. You have to define the specification used for code generation with the following property:

quarkus.openapi.generator.spec=petstore-openapi.json

If you want to change the directory where OpenAPI files must be found, use the property quarkus.openapi.input-base-dir. IMPORTANT: it is relative to the project base directory. For example, if you have a project called MyJavaProject and decide to place them in MyJavaProject/openapi-definitions, use the following property:

quarkus.openapi.input-base-dir=openapi-definitions

If a base package name is not provided, it will be used the default io.apicurio.api. You can customize it with the following property:

quarkus.openapi.generator.base-package=io.petstore

Run mvn compile to generate your classes in target/generated-sources/jaxrs path:

- io.petstore
  - beans
    - Address.java
    - ApiResponse.java
    - Category.java
    - Customer.java
    - Order.java
    - Pet.java
    - Tag.java
    - User.java
  - PetResource.java
  - StoreResource.java
  - UserResource.java

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

package io.petstore;

import java.io.InputStream;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import io.petstore.beans.ApiResponse;
import io.petstore.beans.Pet;

public class PetStoreImpl implements PetResource {

    private static final Map<Long, Pet> PETS = new HashMap<>();

    @Override
    public Pet updatePet(Pet data) {
        return PETS.put(data.getId(), data);
    }

    @Override
    public Pet addPet(Pet data) {
        return PETS.put(data.getId(), data);
    }

    @Override
    public List<Pet> findPetsByStatus(String status) {
        return null;
    }

    @Override
    public List<Pet> findPetsByTags(List<String> tags) {
        return null;
    }

    @Override
    public Pet getPetById(long petId) {
        return PETS.get(petId);
    }

    @Override
    public void updatePetWithForm(long petId, String name, String status) {

    }

    @Override
    public void deletePet(String apiKey, long petId) {
        PETS.remove(petId);
    }

    @Override
    public ApiResponse uploadFile(long petId, String additionalMetadata, InputStream data) {
        return null;
    }
}

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.