OpenAPI

Easily allow your Helidon MP application to serve an OpenAPI document that describes your application’s endpoints.

OpenAPI support in Helidon MP

You can very simply add support for OpenAPI to your Helidon MP application. This document shows what changes you need to make to your application and how to access the OpenAPI document for your application at runtime.

Changing your application

Helidon MP conforms to the MicroProfile OpenAPI specification, which was inspired by the OpenAPI spec itself.

Helidon MP includes a complete OpenAPI example based on the MP quick-start sample app.

To use OpenAPI from your Helidon MP app:

  1. Edit your pom.xml.
  2. Furnish OpenAPI information about your application’s endpoints.
  3. Update your application’s configuration (optional).

Edit your pom.xml

Building the Jandex index

A Jandex index stores information about the classes and methods in your app and what annotations they have. It allows CDI to process annotations faster during your application’s start-up.

Add the Jandex maven plug-in to the <build><plugins> section of your pom.xml:

<plugin>
    <groupId>org.jboss.jandex</groupId>
    <artifactId>jandex-maven-plugin</artifactId>
    <version>1.0.6</version>
    <executions>
      <execution>
        <id>make-index</id>
        <goals>
          <goal>jandex</goal>
        </goals>
      </execution>
    </executions>
</plugin>
Copied

When you build your app maven should include the index META-INF/jandex.idx in the JAR.

Note

If you do not modify your build to create the index then the Helidon MP OpenAPI runtime automatically creates one in memory during app start-up. This slows down your app start-up and, depending on how CDI is configured, might inadvertently miss information.

We strongly recommend using the Jandex plug-in to build the index into your app.

Adding Helidon MP OpenAPI support to your app

Add these two sections to the <dependencies> portion of your pom.xml:

<dependency> 
    <groupId>org.eclipse.microprofile.openapi</groupId>
    <artifactId>microprofile-openapi-api</artifactId>
    <version>1.1.2</version>
</dependency>

<dependency> 
    <groupId>io.helidon.microprofile.openapi</groupId>
    <artifactId>helidon-microprofile-openapi</artifactId>
    <version>1.4.12</version>
    <scope>runtime</scope>
</dependency>
Copied
  • Defines the MicroProfile OpenAPI annotations so you can use them in your code.
  • Adds the Helidon MP OpenAPI runtime support.

Furnish OpenAPI information about your endpoints

Helidon MP OpenAPI combines information from all of the following sources as it builds its in-memory model of your application’s API. It constructs the OpenAPI document from this internal model. Your application can use one or more of these techniques.

Annotate the endpoints in your app

You can add MicroProfile OpenAPI annotations to the endpoints in your source code. These annotations allow the Helidon MP OpenAPI runtime to discover the endpoints and information about them via CDI at app start-up.

Here is one of the endpoints, annotated for OpenAPI, from the example mentioned earlier:

@GET
@Operation(summary = "Returns a generic greeting", 
        description = "Greets the user generically")
@APIResponse(description = "Simple JSON containing the greeting", 
        content = @Content(mediaType = "application/json",
                           schema = @Schema(implementation = GreetingMessage.class)))
@Produces(MediaType.APPLICATION_JSON)
public JsonObject getDefaultMessage() {...}
Copied
  • @Operation gives information about this endpoint.
  • @APIResponse describes the HTTP response and declares its media type and contents.

You can also define any request parameters the endpoint expects, although this endpoint uses none.

This excerpt shows only a few annotations for illustration. The Helidon MP OpenAPI example illustrates more, and the MicroProfile OpenAPI spec describes them all.

Provide a static OpenAPI file

Add a static file at META-INF/openapi.yml, META-INF/openapi.yaml, or META-INF/openapi.json. Tools such as Swagger let you describe your app’s API and they then generate an OpenAPI document file which you can include in your application so OpenAPI can use it.

Write and configure a model reader class

Write a Java class that implements the OpenAPI org.eclipse.microprofile.openapi.OASModelReader interface. Your model reader code programmatically adds elements to the internal model that OpenAPI builds.

Change your application’s MP configuration to set mp.openapi.model.reader as the fully-qualified class name of your class.

Write and configure a filter class

Write a Java class that implements the OpenAPI org.eclipse.microprofile.openapi.OASFilter interface. As OpenAPI composes its internal model, it invokes your filter with each model element before adding the element to the model. Your filter can accept the element as-is, modify it, or suppress it.

Change your application’s configuration to set mp.openapi.filter as the full-qualified class name of your class.

Update your application configuration

Beyond the two config properties that denote the model reader and filter, Helidon MP OpenAPI supports a number of others. These are described in the configuration section of the MicroProfile OpenAPI spec.

Accessing the OpenAPI document

Now your Helidon MP application will automatially respond to an additional endpoint —  /openapi — and it will return the OpenAPI document describing the endpoints in your application.

By default, per the MicroProfile OpenAPI spec, the default format of the OpenAPI document is YAML. There is not yet an adopted IANA YAML media type, but a proposed one specifically for OpenAPI documents that has some support is application/vnd.oai.openapi. That is what Helidon returns, by default.

A client can specify Accept: as either application/vnd.oai.openapi+json or application/json to request JSON.