• Overview

• Maven Coordinates

• Usage

• API

• Configuration

• Examples

• Additional Information

The OpenAPI specification defines a standard way to express the interface exposed by a REST service.

The MicroProfile OpenAPI spec explains how MicroProfile embraces OpenAPI, adding annotations, configuration, and a service provider interface (SPI).

OpenAPI support in Helidon SE draws its inspiration from MicroProfile OpenAPI but does not implement the spec because Helidon SE does not support annotations.

The OpenAPI support in Helidon SE performs two main tasks:

• Build an in-memory model of the REST API your service implements.

• Expose the model in text format (typically YAML) via the /openapi endpoint.

To construct the model, Helidon gathers information about the service API from whichever of these sources are present in the application:

• a model reader

  The SPI defines an interface you can implement in your application for programmatically providing part or all of the model;

• a static OpenAPI document file packaged as part of your service;

• a filter class

  The SPI defines an interface you can implement in your application which can mask parts of the model.

To enable OpenAPI add the following dependency to your project’s pom.xml (see Managing Dependencies).

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

You can very simply add support for OpenAPI to your Helidon SE 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

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

Accessing the REST Endpoint

The MicroProfile OpenAPI JavaDocs give full details of the classes and interfaces you can use in your code. Remember that, although the JavaDocs describe annotations, Helidon SE does not support them.

Helidon SE provides an API for creating and setting up the REST endpoint which serves OpenAPI documents to clients at the /openapi path. Use either static methods on OpenAPISupport or use its Builder to create an instance of OpenAPISupport. Then add that instance to your application’s routing. The example below shows how to do this.

Helidon SE OpenAPI configuration supports the following settings:

Type: io.helidon.openapi.SEOpenAPISupport

openapi

Configuration options

Helidon SE provides a complete OpenAPI example based on the SE QuickStart sample app which includes a model reader and a filter.

Most Helidon SE applications need only to create and register OpenAPISupport.

Register OpenAPISupport

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

Building the Jandex index

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