OpenAPI in SE

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

Maven Coordinates

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

OpenAPI support in Helidon SE

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

OpenAPI support in Helidon SE largely follows the MicroProfile OpenAPI spec. But Helidon SE does not process annotations, which is one way to convey OpenAPI information about the endpoints in your app. You can still use OpenAPI with your Helidon SE app by providing OpenAPI information about the endpoints without using annotations.

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

To use OpenAPI from your Helidon SE app:

  1. Edit your pom.xml.
  2. Update your Java code to register OpenAPISupport.
  3. Furnish OpenAPI information about your application’s endpoints.
  4. Update your application’s Helidon configuration (optional).

Edit your pom.xml

Add a dependency for Helidon SE OpenAPI runtime support. This is a compile-time dependency, because your code must register OpenAPISupport (a class in that artifact) like this:

Register OpenAPISupport in your Java code

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();
Copied
  • Adds the OpenAPISupport service to your server.

Furnish OpenAPI information about your endpoints

Helidon SE 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.

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 configuration to set openapi.model.reader as the fully-qualified class name of your class. Also see Add OpenAPI dependency below.

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 openapi.filter as the full-qualified class name of your class. Also see Add OpenAPI dependency below.

Add OpenAPI dependency

If you implement either a model reader or a filter, add this dependency to your pom.xml:

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

Update application configuration

Helidon SE support for OpenAPI supports a handful of config properties patterned after those described in the MicroProfile OpenAPI spec, two of which were mentioned above.

Helidon SE OpenAPI Config Properties
PropertyUse
openapi.model.readerFully-qualified class name for the model reader
openapi.filterFully-qualified class name for the filter
openapi.serversLists servers that provide connectivity information
openapi.servers.pathPrefix for config properties specifying alternative servers for given paths
openapi.servers.operationPrefix for config properties specifying alternative servers for given operations

For more information on what these settings do consult the MicroProfile OpenAPI spec.

Helidon SE also supports additional properties specific to Helidon.

OpenAPI support configuration

Type: io.helidon.openapi.OpenAPISupport

Configuration options

Optional configuration options
key

type

default value

description

cors

CrossOriginConfig

 

Assigns the CORS settings for the OpenAPI endpoint.

static-file

string

META-INF/openapi.*

Sets the file system path of the static OpenAPI document file. Default types are json, yaml, and yml.

ui

OpenApiUi

 

Assigns the OpenAPI UI builder the OpenAPISupport service should use in preparing the UI.

web-context

string

/openapi

Sets the web context path for the OpenAPI endpoint.

Set these config properties in one of the config sources your app uses so the Helidon config system will load them. Often developers use application.yaml at the top level of the application JAR.

Accessing the OpenAPI document

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

By default, Helidon OpenAPI returns the OpenAPI document in 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.

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