OpenAPI in Helidon

Overview

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 (YAML or JSON) via the /openapi endpoint.

To construct the model, Helidon gathers information about the service API from a static OpenAPI document file packaged as part of your service.

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

Usage

Automatic Registration (default)

Simply by adding the dependency described above you add support for OpenAPI to your Helidon SE application. Because Helidon automatically discovers the OpenAPI feature, you do not have to make any changes to your application code.

Explicit Registration

To control the behavior of the OpenAPI feature programmatically, you can add and configure the OpenAPI feature explicitly as explained below.

Create and Register `OpenApiFeature` in your application

Helidon SE provides the OpenApiFeature class which your application uses to assemble the in-memory model and expose the /openapi endpoint to clients. You can create an instance either using a static create method or by instantiating its Builder. The example below illustrates one way to do this.

Furnish OpenAPI information about your endpoints

Your application supplies data for the OpenAPI model using a static OpenAPI file.

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.

Accessing the REST Endpoint

Once you have added the SE OpenAPI dependency to your project, if you are using auto-discovery—or if you are not using auto-discovery and you have added code to register the OpenApiFeature object with your routing—then your application responds to the built-in endpoint — /openapi — and returns the OpenAPI document describing the endpoints in your application.

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.

In addition, a client can specify the HTTP header Accept as either application/vnd.oai.openapi+json or application/json to request JSON. Alternatively, the client can pass the query parameter format as either JSON or YAML to receive application/json or application/vnd.oai.openapi (YAML) output, respectively.

API

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 OpenApiFeature or use its Builder. Then add that instance or builder to your application’s routing. The example below shows how to do this.

Configuration

Helidon SE OpenAPI configuration supports the following settings:

Type: io.helidon.openapi.OpenApiFeature

This is a standalone configuration type, prefix from configuration root: openapi

Configuration options

Optional configuration options

key	type	default value	description
`cors`	CrossOriginConfig		CORS config. @return CORS config
`enabled`	boolean	`true`	Sets whether the feature should be enabled. @return `true` if enabled, `false` otherwise
`manager`	io.helidon.openapi.OpenApiManager (service provider interface)		OpenAPI manager. @return the OpenAPI manager
`permit-all`	boolean		Whether to allow anybody to access the endpoint. @return whether to permit access to metrics endpoint to anybody, defaults to `true` @see #roles()
`roles`	string[]		Hints for role names the user is expected to be in. @return list of hints
`services`	io.helidon.openapi.OpenApiService[] (service provider interface)		OpenAPI services. @return the OpenAPI services
`static-file`	string		Path of the static OpenAPI document file. Default types are `json`, `yaml`, and `yml`. @return location of the static OpenAPI document file
`web-context`	string	`/openapi`	Web context path for the OpenAPI endpoint. @return webContext to use

Examples

Helidon SE provides a complete OpenAPI example based on the SE QuickStart sample app.

Most Helidon SE applications need only add the dependency as explained above; Helidon discovers and registers OpenAPI automatically. The example below shows how to create and register OpenApiFeature explicitly instead.

Register `OpenApiFeature` explicitly

Java Code to Create and Register OpenApiFeature

WebServer server = WebServer.builder()
        .config(config.get("server"))
        .addFeature(OpenApiFeature.create(config.get("openapi"))) 
        .routing(Main::routing)
        .build()
        .start();