Quarkus - Kiota

Quarkus' extension for generation of fully typed, client side SDKs based on OpenAPI specification files.

This extension is based on the Microsoft Kiota generator.

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

First of all you need to add or update the quarkus-maven-plugin configuration with the following:

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

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

<dependency>
  <groupId>io.kiota</groupId>
  <artifactId>quarkus-kiota</artifactId>
  <version>{project.version}</version>
</dependency>

Now, create a new folder named openapi under src/main/ and add OpenAPI spec files there. Supported file extensions are: json, yaml, yml.

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.kiota.petstore.json.package-name=com.mycompany

If a base package name is not provided, it will be used the default io.apisdk.<filename>. For example, io.apisdk.petstore.json.

You can customize the name of Api Client class using the following property:

quarkus.kiota.petstore.json.class-name=MyApiClient

Now add the additional dependencies to compile the project:

<dependency>
  <groupId>com.microsoft.kiota</groupId>
  <artifactId>microsoft-kiota-abstractions</artifactId>
  <version>${kiota.libs.version}</version>
</dependency>
<dependency>
  <groupId>io.kiota</groupId>
  <artifactId>kiota-http-vertx</artifactId> <!-- alternatively <artifactId>kiota-http-jdk</artifactId> -->
  <version>{version}</version>
</dependency>
<dependency>
  <groupId>io.kiota</groupId>
  <artifactId>kiota-serialization-jackson-quarkus</artifactId>
  <version>{version}</version>
</dependency>
<dependency>
  <groupId>com.microsoft.kiota</groupId>
  <artifactId>microsoft-kiota-serialization-text</artifactId>
  <version>${kiota.libs.version}</version>
</dependency>
<dependency>
  <groupId>com.microsoft.kiota</groupId>
  <artifactId>microsoft-kiota-serialization-form</artifactId>
  <version>${kiota.libs.version}</version>
</dependency>
<dependency>
  <groupId>com.microsoft.kiota</groupId>
  <artifactId>microsoft-kiota-serialization-multipart</artifactId>
  <version>${kiota.libs.version}</version>
</dependency>
<dependency>
  <groupId>jakarta.annotation</groupId>
  <artifactId>jakarta.annotation-api</artifactId>
</dependency>

Running mvn compile generates your classes under the target/generated-sources/kiota folder. You can reference and use the generated code in your project, for example:

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

import io.apisdk.petstore.json.ApiClient;
import io.kiota.http.vertx.VertXRequestAdapter;
import io.vertx.core.Vertx;

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

  @Inject Vertx vertx;

  RequestAdapter adapter = new VertXRequestAdapter(vertx);
  ApiClient client = new ApiClient(adapter);
}

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

With Kiota you can plug in any authentication mechanism provided by the underlying HTTP client.

For example, when using the VertX HTTP client you can configure a Bearer Access Token with OIDC like:

OAuth2Options options =
        new OAuth2Options()
                .setFlow(OAuth2FlowType.CLIENT)
                .setClientId(CLIENT_ID)
                .setTokenPath(keycloakUrl + "token")
                .setClientSecret(CLIENT_SECRET);

OAuth2Auth oAuth2Auth = OAuth2Auth.create(vertx, options);

Oauth2Credentials oauth2Credentials = new Oauth2Credentials();

OAuth2WebClient oAuth2WebClient =
        OAuth2WebClient.create(WebClient.create(vertx), oAuth2Auth)
                .withCredentials(oauth2Credentials);

var adapter = new VertXRequestAdapter(oAuth2WebClient);

Full configuration

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.kiota.os

Overrides the detected Operating System

Environment variable: QUARKUS_KIOTA_OS

string

quarkus.kiota.arch

Overrides the detected Architecture

Environment variable: QUARKUS_KIOTA_ARCH

string

quarkus.kiota.provided

The path to a kiota executable location to be used. When set, the kiota version is not going to be checked/used.

Environment variable: QUARKUS_KIOTA_PROVIDED

string

quarkus.kiota.release.url

The path to a kiota executable location to be used

Environment variable: QUARKUS_KIOTA_RELEASE_URL

string

https://github.com/microsoft/kiota/releases

quarkus.kiota.version

The kiota version to be used. If not provided we are going to try to resolve "latest" from the GitHub API. Please, set this property in any production grade project.

Environment variable: QUARKUS_KIOTA_VERSION

string

quarkus.kiota.timeout

The timeout to be used when running the kiota CLI.

Environment variable: QUARKUS_KIOTA_TIMEOUT

string

30

Configuration resolved based on the OpenAPI description file name This configuration section is optional

Type

Default

quarkus.kiota.spec-name.class-name

The generated API client class name.

Environment variable: QUARKUS_KIOTA_SPEC_NAME_CLASS_NAME

string

ApiClient

quarkus.kiota.spec-name.package-name

The generated API client package name.

Environment variable: QUARKUS_KIOTA_SPEC_NAME_PACKAGE_NAME

string

io.apisdk

quarkus.kiota.spec-name.include-path

The glob expression to be used to identify the endpoints to be included in the generation.

Environment variable: QUARKUS_KIOTA_SPEC_NAME_INCLUDE_PATH

string

quarkus.kiota.spec-name.exclude-path

The glob expression to be used to identify the endpoints to be excluded from the generation.

Environment variable: QUARKUS_KIOTA_SPEC_NAME_EXCLUDE_PATH

string

quarkus.kiota.spec-name.serializer

ADVANCED: The serializers to be used in the generated code.

Environment variable: QUARKUS_KIOTA_SPEC_NAME_SERIALIZER

list of string

quarkus.kiota.spec-name.deserializer

ADVANCED: The deserializers to be used in the generated code.

Environment variable: QUARKUS_KIOTA_SPEC_NAME_DESERIALIZER

list of string