Project Helidon and OpenAPI

Here’s how to use OpenAPI in your Helidon SE and MP apps.

Helidon is a collection of Java libraries for writing microservices. Helidon MP supports MicroProfile, and Helidon SE offers a functional-style API, both of which help you write microservices in Java quickly.

Beginning with release 1.1.1, Helidon supports OpenAPI. Helidon MP implements the MicroProfile OpenAPI spec, and you can support OpenAPI in your SE app as well. Our documentation describes all the details for MP and SE, and our GitHub repository includes fully-working example apps with OpenAPI for MP and SE.

This article shows the very simplest way to add OpenAPI support to your applications.

The changes you make depend on whether you use Helidon MP or SE, so there are separate sections for each below. The way you access your app’s OpenAPI document is the same, so that’s described once near the end.

Using OpenAPI in Helidon MP

Update your pom.xml

Build a Jandex index that will be used to speed up scanning for OpenAPI-related annotations. In the <build><plugins> section add:

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

Add dependencies so you can use OpenAPI annotations (see below) and so the Helidon OpenAPI runtime (and the rest of Helidon support for MicroProfile 2.2) will be present when your app runs.

<dependency>
    <groupId>org.eclipse.microprofile.openapi</groupId>
    <artifactId>microprofile-openapi-api</artifactId>
    <version>1.1.2</version>
</dependency
<dependency>
    <groupId>io.helidon.microprofile.bundles</groupId>
    <artifactId>helidon-microprofile-2.2</artifactId>
    <version>1.1.2</version>
</dependency>

Annotate the endpoints

Add OpenAPI annotations to your app’s endpoints.

Here’s a simple GET endpoint from the working example, updated for OpenAPI:

@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() {...}

The @Operation and @APIResponse annotations are new.

Using OpenAPI in Helidon SE

OpenAPI support in SE is basically the same as in MP except for annotation processing. SE does not do annotation processing, so OpenAPI cannot rely on that to gather endpoint information.

Instead, your SE app will typically include a static file containing the OpenAPI document that describes the app’s endpoints.

Follow these steps:

Update your pom.xml

Add this dependency:

<dependency>
     <groupId>io.helidon.openapi</groupId>
     <artifactId>helidon-openapi</artifactId>
     <version>1.1.2</version>
</dependency>

Register OpenAPISupport in your code

Your SE app will already have code similar to this. Just add the line that registers OpenAPISupport:

Config config = Config.create();
...
return Routing.builder()
         .register(JsonSupport.create())
         .register(OpenAPISupport.create(config))
         .register(health)
         .register(metrics)
         .register("/greet", greetService)
         .build();

Add a static OpenAPI document file

Tools such as Swagger let you describe your app’s API and they then generate an OpenAPI document file. Or you can just use an editor and create the file manually.

Once you have the file, add it to your project at META-INF/openapi.yml. The Helidon OpenAPI support will find it automatically.

Access the OpenAPI document

After you make the changes and build your app, run it. Then send a GET request to the automatically-supported/openapi endpoint. You will see a lot of output, including this describing the endpoint in the source code above:

paths:
  /greet:
    get:
      summary: Returns a generic greeting
      description: Greets the user generically
      responses:
        default:
          description: Simple JSON containing the greeting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GreetingMessage'

What next?

We’ve just scratched the surface here. For example, your MP or SE app can contain your own code that programmatically adds to or changes the OpenAPI model of your endpoints: model readers and filters.

In fact, Helidon OpenAPI support combines endpoint information from all of these sources:

• static documents,
• annotations (only for MP),
• configuration settings,
• model reader, and
• filter.

Our documentation at https://helidon.io/docs goes much further. Look for OpenAPI (that’s for SE) and MicroProfile -> OpenAPI in the navigation panel. Here are direct links to the SE and MP OpenAPI doc pages.

And remember the examples in the Helidon GitHub site are ready to build and run: openapi for SE and openapi-basic for MP.