Major Improvements with Helidon and OpenAPI

With releases 2.5.5 and 3.1.0, Helidon significantly improves its participation in the OpenAPI ecosystem. You can now take advantage of

• powerful code generation from OpenAPI documents, and
• a convenient user interface for test-driving your application’s operations.

This is in addition to built-in support for OpenAPI which Helidon has included almost from its beginning.

Existing OpenAPI support — a longstanding Helidon feature

Since its early releases, Helidon has had strong support for OpenAPI.

With Helidon SE you can package a static OpenAPI document with your service or even write your own code to build the document at runtime. Helidon then automatically serves the document at /openapi.

Helidon MP (which implements the MicroProfile OpenAPI specification) in addition can automatically derive an OpenAPI document from the JAX-RS endpoints in your application.

New, stronger support in OpenAPITools generators for Helidon

The OpenAPITools generator is an open-source project separate from the Helidon project which generates code for a wide variety of platforms and languages from an OpenAPI document. Starting with release 6.2.1, that project provides much stronger support for generating Helidon SE and MP servers and clients.

The Helidon team has contributed two new generators — java-helidon-server and java-helidon-client — to the OpenAPITools generator project. Each new generator supports two libraries — mp and se — so you can generate code for either flavor of Helidon.

The java-helidon-server generator creates code to implement in a Helidon server the operations declared in an OpenAPI document. The generated code includes skeleton implementations which you then extend with business logic you write yourself. If your OpenAPI document changes, you can regenerate the code without disturbing your customizations.

The java-helidon-client generator creates a library to invoke your operations as implemented in a server. (The server does not have to be generated using the tool; it does need to honor the OpenAPI document you use to generate the client.) Most developers would add a dependency on the generated client library from one or more other projects that need to contact the server.

As a developer, once you have an OpenAPI document which describes your application’s endpoints, you can use the new generators in several ways:

1. Use the OpenAPITools CLI to create an entire new Helidon MP or SE project which contains generated code to implement your operations (for servers) or invoke your operations (for clients).
2. Use the OpenAPITools CLI to update an existing server or client project with revised interfaces or classes that reflect any changes in the OpenAPI document.
3. Invoke the Maven plug-in for the OpenAPITools generator from your project’s pom.xml. Each time you build the project, the plug-in recreates the generated files according to the current version of the OpenAPI document.

Many developers will choose to use the Helidon CLI to create a project, then edit the pom.xml to invoke the OpenAPITools generator Maven plug-in as an automatic part of the build.

To use the generator CLI, first download it using a command similar to this:

curl https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.2.1/openapi-generator-cli-6.2.1.jar \
     -o openapi-generator-cli.jar

Then you can create a Helidon MP project from your OpenAPI document very simply:

mkdir myproject

cd myproject

java -jar ${path-to-generator}/openapi-generator-cli.jar \
  generate \
  --input-spec ${path-to-openapi-document}myAppOpenAPI.yaml \
  --generator-name java-helidon-server \
  --library mp

To create an SE project, change the--library to se. To generate a client, change the --generator-name to java-helidon-client.

The OpenAPITools site describes how to use the tool in general, for all generators and all languages and frameworks. We have added to our own Helidon web site new documentation which explains in detail not only how to use the tool to generate an MP project or an SE project but also how to then work with the generated files to complete your project. We have also added examples which show generated Helidon MP and SE projects along with detailed step-by-step instructions.

Integration with the SmallRye OpenAPI user interface

SmallRye offers an OpenAPI user interface which displays a web page based on your application’s OpenAPI document. Through that UI, users can invoke the operations declared in the document. While not generally suitable for end-users, the OpenAPI UI can be useful for demonstrating and “test driving” your service’s endpoints.

Helidon now includes a new, optional component which plugs the OpenAPI UI into your Helidon SE or MP application very simply. In many cases you can simply add a single runtime dependency to your project:

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

Rebuild and run your project, and then use a browser to access/openapi/ui which launches the UI.

Here is how the UI looks for the Helidon MP QuickStart application:

The screen lists the operations which the MP QuickStart application’s OpenAPI document defines. To run one of the operations:

• Click on the operation.
• Click “Try it out”.
• Fill in any parameters you want to pass to the operation (the first red box in the image below).
• Click “Execute” (red arrow).

The UI sends the request to the operation and displays the response (second red box):

The Helidon documentation contains new sections describing in detail how to add the UI to your MP application and SE application. You can even customize the path where you want the UI to respond.

Next Steps

Take a look at the expanded Helidon documentation describing the new generators and the new UI integration.

• Generating MP applications https://helidon.io/docs/latest/index.html#/mp/openapi/openapi-generator
• Generating SE applications https://helidon.io/docs/latest/index.html#/se/openapi/openapi-generator
• Integrating the OpenAPI UI into MP applications https://helidon.io/docs/latest/index.html#/mp/openapi/openapi-ui
• Integrating the OpenAPI UI into SE applications https://helidon.io/docs/latest/index.html#/se/openapi/openapi-ui

Browse the examples of using the generators:

• Example using the OpenAPI generator for an MP application
  https://github.com/helidon-io/helidon/tree/3.1.0/examples/openapi-tools/quickstart-mp
• Example using the OpenAPI generator for an SE application https://github.com/helidon-io/helidon/tree/3.1.0/examples/openapi-tools/quickstart-se

Then you will be ready to use the generators and the UI in your own projects with your own OpenAPI documents.