Helidon with Swagger

Swagger UI is a great resource to generate and show docs for (java based) APIs. While adding a Swagger UI to a maven based project should be straight forward, adding a few annotations to your class and some dependencies to your pom.xml. It turned out there are a few steps involved for Helidon built projects. This article presents those details.

TL;DR

This article discusses the how-to’s of setting up Swagger UI to a project built with Helidon MP . A working example is on Github.

Why this post?

It took a while for me to setup Swagger UI to my API-only project built with Helidon MP. Wanted to share this article to my fellow developers, to save time.

Getting started

Building from scratch

If you already have an existing project, skip steps 1 and 2

1.Create a new project using Helidon MP’s archetype

mvn -U archetype:generate 
    -DinteractiveMode=false
    -DarchetypeGroupId=io.helidon.archetypes
    -DarchetypeArtifactId=helidon-quickstart-mp
    -DarchetypeVersion=2.3.4
    -DgroupId=io.helidon.examples
    -DartifactId=helidon-quickstart-mp
    -Dpackage=io.helidon.examples.quickstart.mp

2.Build and Run the default project

mvn package
java -jar ./target/helidon-quickstart-mp.jar

3.Add these dependencies to pom.xml

<!-- https://mvnrepository.com/artifact/org.eclipse.microprofile.openapi/microprofile-openapi-api -->
<dependency>
   <groupId>org.eclipse.microprofile.openapi</groupId>
   <artifactId>microprofile-openapi-api</artifactId>
   <version>1.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.helidon.microprofile.openapi/helidon-microprofile-openapi -->
<!-- NOTE: I built the project using Helidon MP 2.3.4, pleaase us the version per your project -->
<dependency>
   <groupId>io.helidon.microprofile.openapi</groupId>
   <artifactId>helidon-microprofile-openapi</artifactId>
   <version>2.3.4</version>
</dependency>
<!-- https://mvnrepository.com/artifact/org.microprofile-ext.openapi-ext/openapi-ui -->
<dependency>
   <groupId>org.microprofile-ext.openapi-ext</groupId>
   <artifactId>openapi-ui</artifactId>
   <version>1.1.5</version>
</dependency>

4. Build and Run the project again

mvn package
java -jar ./target/helidon-quickstart-mp.jar

5. In your browser, use the url “openapi-ui” . By default it would be like http://localhost:9393/your-project/openapi-ui

Screenshot of Swagger-UI (like) when added to a Helidon MP built project - Suren K

That’s it.

Adding docs to your APIs

We need to add the required Annotations for docs to be generated. Example below (in the file)

@Path("/greeting")
@PUT
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
@RequestBody(name = "greeting",
   required = true,
   content = @Content(mediaType = "application/json",
   schema = @Schema(type = SchemaType.STRING, example = "{\"greeting\" : \"Hola\"}")))
@APIResponses({
   @APIResponse(name = "normal", responseCode = "204", description = "Greeting updated"),
   @APIResponse(name = "missing 'greeting'", responseCode = "400",
      description = "JSON did not contain setting for 'greeting'")})
 public Response updateGreeting(JsonObject jsonObject) { ... }

Background

You may have observed, we did not use Swagger-ui dependency but instead used Open-API. We can add MicroProfile OpenAPI annotations to Helidon MP built project, and Helidon will automatically generate the OpenAPI document for you and provide an endpoint where clients can retrieve it.

For more details, you may go here

• Helidon supports OpenAPI and

• Swagger also supports OpenAPI Specifications and

• https://github.com/microprofile-extensions/openapi-ext/tree/main/openapi-ui and

• https://github.com/oracle/helidon/tree/master/examples/openapi

Resources

• Working example on Github - https://github.com/ksurendra/helidon-mp-swagger

• Helidon resources https://github.com/oracle/helidon

• Swagger resources https://swagger.io/docs/