OpenAPI + Swagger UI with Micronaut Application

Introduction

APIs (Application Programming Interfaces) are the backbone of modern software, connecting applications and systems seamlessly. In this interconnected world, OpenAPI has emerged as a game-changer for designing, building, and managing APIs.

What is OpenAPI?

OpenAPI is a specification for designing APIs. Formerly known as Swagger, it provides a standard way to describe the structure of your APIs in a machine-readable format, typically using a YAML or JSON document. This document acts as the blueprint for your API, detailing endpoints, request/response schemas, authentication methods, and more.

Micronaut includes support for producing OpenAPI (Swagger) YAML at compilation time. Micronaut will at compile time produce a OpenAPI 3.x compliant YAML file just based on the regular Micronaut annotations and the javadoc comments within your code.

Micronaut Launch

https://micronaut.io/launch?type=DEFAULT&name=demo&package=com.example&javaVersion=JDK_21&lang=JAVA&build=GRADLE_KOTLIN&test=JUNIT&features=openapi&features=swagger-ui&features=eclipsestore&features=eclipsestore-rest

Using the Micronaut CLI

mn create-app --build=gradle_kotlin --jdk=21 --lang=java --test=junit --features=openapi,swagger-ui,eclipsestore,eclipsestore-rest schoolstaff.perk

Dependencies

annotationProcessor("io.micronaut.openapi:micronaut-openapi")

To use the Swagger Annotations or Micronaut OpenAPI annotations add them to compile classpath

Once dependencies have been configured a minimum requirement is to add a @OpenAPIDefinition annotation to your Application class

import io.micronaut.runtime.Micronaut;
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Contact;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.info.License;


@OpenAPIDefinition(
        info = @Info(
                title = "Sample application",
                version = "0.0",
                description = "My API",
                license = @License(name = "Apache 2.0", url = "https://foo.bar"),
                contact = @Contact(url = "https://gigantic-server.com", name = "Sample", email = "[e-mail]")
        )
)
public class Application {

    public static void main(String[] args) {
        Micronaut.run(Application.class);
    }
}

With that in place, you compile your project and a OpenAPI YAML file will be generated to the META-INF/swagger directory of your project’s class output. For example, the above configuration generates:

For Java build/classes/java/main/META-INF/swagger/hello-world-0.0.yml

openapi: 3.0.1
info:
  title: the title
  description: My API
  contact:
    name: Fred
    url: https://gigantic-server.com
    email: [e-mail]
  license:
    name: Apache 2.0
    url: https://foo.bar
  version: "0.0"

In the application.properties file expose the swagger path

micronaut.router.static-resources.swagger-ui.mapping=/swagger-ui/**
micronaut.router.static-resources.swagger-ui.paths=classpath\:META-INF/swagger/views/swagger-ui
micronaut.router.static-resources.swagger.mapping=/swagger/**
micronaut.router.static-resources.swagger.paths=classpath\:META-INF/swagger

The swagger is exposed on this URL - http://localhost:8080/swagger-ui/index.html