Java / Maven

Visualize an OpenAPI specification of your Micronaut application with Swagger UI

Learn how to generate an OpenAPI specification of your Micronaut application at build time and visualize it with Swagger UI.

Sergio del Amo

On this guide

In this section

Getting Started

In this guide, we will create a Micronaut application written in Java.

What you will need

To complete this guide, you will need the following:

Some time on your hands
A decent text editor or IDE (e.g. IntelliJ IDEA)
JDK 21 or greater installed with JAVA_HOME configured appropriately

Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

Download and unzip the source

Writing the Application

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

mn create-app example.micronaut.micronautguide \
    --features=openapi,swagger-ui,validation \
    --build=maven \
    --lang=java \
    --test=junit

Note	If you don’t specify the `--build` argument, Gradle with the Kotlin DSL is used as the build tool. If you don’t specify the `--lang` argument, Java is used as the language. If you don’t specify the `--test` argument, JUnit is used for Java and Kotlin, and Spock is used for Groovy.

The previous command creates a Micronaut application with the default package example.micronaut in a directory named micronautguide.

If you use Micronaut Launch, select Micronaut Application as application type and add openapi, swagger-ui, and validation features.

Note	If you have an existing Micronaut application and want to add the functionality described here, you can view the dependency and configuration changes from the specified features, and apply those changes to your application.

Diff

Setup IntelliJ IDEA to develop Micronaut Applications.

Micronaut OpenAPI

To use Micronaut OpenAPI, add the micronaut-openapi annotation processor and the Micronaut OpenAPI annotations as a compile-only dependency:

pom.xml

<!-- Add the following to your annotationProcessorPaths element -->
<path>
    <groupId>io.micronaut.openapi</groupId>
    <artifactId>micronaut-openapi</artifactId>
</path>
<dependency>
    <groupId>io.micronaut.openapi</groupId>
    <artifactId>micronaut-openapi-annotations</artifactId>
    <scope>compile</scope>
</dependency>

The micronaut-openapi-annotations dependency brings the Swagger annotations dependency transitively.

Latest Guide Controller

First, let’s create a controller that exposes the Micronaut Guides information.

Guides Model

We support different build tools per guide:

src/main/java/example/micronaut/BuildTool.java

package example.micronaut;

public enum BuildTool {

    GRADLE, MAVEN
}

A guide may be written in multiple languages:

src/main/java/example/micronaut/Language.java

package example.micronaut;

public enum Language {

    GROOVY,
    JAVA,
    KOTLIN
}

Thus, we have several options per guide:

src/main/java/example/micronaut/Option.java

package example.micronaut;

import io.micronaut.serde.annotation.Serdeable;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;

@Serdeable // 
public record Option(@NotNull Language language, // 
                     @NotNull BuildTool buildTool, // 
                     @NotBlank String url) { // 
}

1	Declare the `@Serdeable` annotation at the type level in your source code to allow the type to be serialized or deserialized.
2	Use `jakarta.validation.constraints` Constraints to ensure the data matches your expectations.

The following Java record represents a Micronaut Guide:

src/main/java/example/micronaut/Guide.java

package example.micronaut;

import io.micronaut.core.annotation.Nullable;
import io.micronaut.serde.annotation.Serdeable;
import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Size;
import java.time.LocalDate;
import java.util.List;

@Serdeable // 
public record Guide(@NotBlank String title,
                    @NotBlank String intro,
                    @NotNull @Size(min = 1) List<@NotBlank String> authors, // 
                    @Nullable List<@NotBlank String> tags,
                    @NotNull @Size(min = 1) List<@NotBlank String> categories,
                    @Schema(format = "yyyy-MM-dd", example = "2018-05-23") @NotNull LocalDate publicationDate, // 
                    @NotBlank String slug,
                    @NotBlank String url,
                    @NotNull @Size(min = 1) List<@NotNull @Valid Option> options) {
}

1	Declare the `@Serdeable` annotation at the type level in your source code to allow the type to be serialized or deserialized.
2	Use `jakarta.validation.constraints` Constraints to ensure the data matches your expectations.
3	You can use the swagger annotation `@Schema` to customize the generated OpenAPI specification.

Controller

Let’s create a controller for which we will generate an OpenAPI Specification at build time.

src/main/java/example/micronaut/LatestGuidesController.java

package example.micronaut;

import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import java.time.LocalDate;
import java.util.Collections;
import java.util.List;

@Controller("/latest") // 
class LatestGuidesController {

    private static final List<Guide> GUIDES = Collections.singletonList(
            new Guide("Creating your first Micronaut application",
                    "Learn how to create a Hello World Micronaut application with a controller and a functional test.",
                    List.of("Iván López", "Sergio dle Amo"),
                    List.of("junit","getting_started","graalvm"),
                    List.of("Getting Started"),
                    LocalDate.of(2018, 5, 23),
                    "creating-your-first-micronaut-app",
                    "https://guides.micronaut.io/latest/creating-your-first-micronaut-app.html",
                    List.of(new Option(Language.JAVA, BuildTool.GRADLE, "https://guides.micronaut.io/latest/creating-your-first-micronaut-app-gradle-java.html"),
                            new Option(Language.GROOVY, BuildTool.GRADLE, "https://guides.micronaut.io/latest/creating-your-first-micronaut-app-gradle-groovy.html"),
                            new Option(Language.KOTLIN, BuildTool.GRADLE, "https://guides.micronaut.io/latest/creating-your-first-micronaut-app-gradle-kotlin.html"),
                            new Option(Language.JAVA, BuildTool.MAVEN, "https://guides.micronaut.io/latest/creating-your-first-micronaut-app-maven-java.html"),
                            new Option(Language.GROOVY, BuildTool.MAVEN, "https://guides.micronaut.io/latest/creating-your-first-micronaut-app-maven-groovy.html"),
                            new Option(Language.KOTLIN, BuildTool.MAVEN, "https://guides.micronaut.io/latest/creating-your-first-micronaut-app-maven-kotlin.html")
                            ))
    );

    @Get("/guides.json") // 
    List<Guide> latestGuides() {
        return GUIDES;
    }
}

We could test such a controller with:

src/test/java/example/micronaut/LatestGuidesControllerTest.java

package example.micronaut;

import io.micronaut.http.HttpRequest;
import io.micronaut.http.client.BlockingHttpClient;
import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.annotation.Client;
import io.micronaut.http.uri.UriBuilder;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import org.junit.jupiter.api.Test;

import java.net.URI;

import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
import static org.junit.jupiter.api.Assertions.assertTrue;

@MicronautTest // 
class LatestGuidesControllerTest {

    @Test
    void guidesEndpoint(@Client("/") HttpClient httpClient) { // 
        BlockingHttpClient client = httpClient.toBlocking();
        URI uri = UriBuilder.of("/latest").path("guides.json").build();
        HttpRequest<?> request = HttpRequest.GET(uri);
        String json = assertDoesNotThrow(() -> client.retrieve(request));
        assertTrue(json.contains("2018-05-23"));
    }
}

1	Annotate the class with `@MicronautTest` so the Micronaut framework will initialize the application context and the embedded server. More info.
2	Inject the `HttpClient` bean and point it to the embedded server.

@OpenApiSpecification

The Micronaut OpenAPI integration requires a class to be annotated with @OpenApiSpecification. Modify Application.java and annotate it.

src/main/java/example/micronaut/Application.java

package example.micronaut;

import io.micronaut.runtime.Micronaut;
import io.swagger.v3.oas.annotations.*;
import io.swagger.v3.oas.annotations.info.*;
import io.swagger.v3.oas.annotations.servers.Server;

@OpenAPIDefinition(
    info = @Info(
            title = "micronaut-guides",
            version = "1.0"
    ), servers = @Server(url = "https://guides.micronaut.io")
) // 
public class Application {

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

OpenAPI Generated at Compile Time

By adding the @OpenApiSpecification annotation to Application, an OpenAPI specification is generated at compile time. You can test it as follows:

src/test/java/example/micronaut/OpenApiGeneratedTest.java

package example.micronaut;

import io.micronaut.core.io.ResourceLoader;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.assertTrue;

@MicronautTest(startApplication = false) // 
class OpenApiGeneratedTest {

    @Test
    void buildGeneratesOpenApi(ResourceLoader resourceLoader) {
        assertTrue(resourceLoader.getResource("META-INF/swagger/micronaut-guides-1.0.yml").isPresent());
    }
}

1	Annotate the class with `@MicronautTest` so the Micronaut framework will initialize the application context. This test does not need the embedded server. Set `startApplication` to `false` to avoid starting it.

Expose the OpenAPI Specification

We can expose the OpenAPI specification generated at compile time as a static resource with the following configuration:

src/main/resources/application.properties

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

You can test that the OpenAPI specification is available:

src/test/java/example/micronaut/OpenApiExposedTest.java

package example.micronaut;

import io.micronaut.http.client.BlockingHttpClient;
import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.annotation.Client;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;

@MicronautTest // 
class OpenApiExposedTest {

    @Test
    void openApi(@Client("/") HttpClient httpClient) { // 
        BlockingHttpClient client = httpClient.toBlocking();
        assertDoesNotThrow(() -> client.exchange("/swagger/micronaut-guides-1.0.yml"));
    }
}

1	Annotate the class with `@MicronautTest` so the Micronaut framework will initialize the application context and the embedded server. More info.
2	Inject the `HttpClient` bean and point it to the embedded server.

Swagger UI

To simplify the visualization of the OpenAPI specification, we are going to use Swagger UI.

Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your OpenAPI (formerly known as Swagger) Specification, with the visual documentation making it easy for back end implementation and client-side consumption.

To generate Swagger UI HTML, create an openapi.properties file in the root of your project and add:

swagger-ui.enabled=true

You can write a test to verify that Swagger UI HTML is generated at compile time.

java/src/test/java/example/micronaut/SwaggerUiGeneratedTest.java

package example.micronaut;

import io.micronaut.core.io.ResourceLoader;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.assertTrue;

@MicronautTest(startApplication = false) // 
class SwaggerUiGeneratedTest {

    @Test
    void buildGeneratesOpenApi(ResourceLoader resourceLoader) {
        assertTrue(resourceLoader.getResource("META-INF/swagger/views/swagger-ui/index.html").isPresent());
    }
}

1	Annotate the class with `@MicronautTest` so the Micronaut framework will initialize the application context. This test does not need the embedded server. Set `startApplication` to `false` to avoid starting it.

Expose Swagger UI

We can expose the Swagger UI HTML generated at compile time as a static resource with the following configuration:

src/main/resources/application.properties

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

You can test that Swagger UI is available:

java/src/test/java/example/micronaut/SwaggerUiTest.java

package example.micronaut;

import io.micronaut.http.client.BlockingHttpClient;
import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.annotation.Client;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;

@MicronautTest // 
class SwaggerUiTest {

    @Test
    void openApi(@Client("/") HttpClient httpClient) { // 
        BlockingHttpClient client = httpClient.toBlocking();
        assertDoesNotThrow(() -> client.exchange("/swagger-ui/index.html"));
    }
}

1	Annotate the class with `@MicronautTest` so the Micronaut framework will initialize the application context and the embedded server. More info.
2	Inject the `HttpClient` bean and point it to the embedded server.

Home Controller

Next, create a controller that redirects to the Swagger UI endpoint.

java/src/main/java/example/micronaut/HomeController.java

package example.micronaut;

import io.micronaut.http.HttpResponse;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.uri.UriBuilder;
import io.swagger.v3.oas.annotations.Hidden;
import java.net.URI;

@Controller // 
class HomeController {

    private final static URI SWAGGER_UI = UriBuilder.of("/swagger-ui").path("index.html").build();

    @Get // 
    @Hidden // 
    HttpResponse<?> home() {
        return HttpResponse.seeOther(SWAGGER_UI);
    }
}

1	The class is defined as a controller with the @Controller annotation mapped to the path `/`.
2	The @Get annotation maps the method to an HTTP GET request.
3	If you annotate a route with the swagger annotation `@Hidden`, the compile-time generated OpenAPI specification does not include it.

Write a test that verifies the redirection and checks that the endpoint is not included in the OpenAPI specification:

java/src/test/java/example/micronaut/HomeControllerTest.java

package example.micronaut;

import io.micronaut.context.annotation.Property;
import io.micronaut.core.util.StringUtils;
import io.micronaut.http.HttpHeaders;
import io.micronaut.http.HttpResponse;
import io.micronaut.http.HttpStatus;
import io.micronaut.http.client.BlockingHttpClient;
import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.annotation.Client;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.*;

@Property(name = "micronaut.http.client.follow-redirects", value = StringUtils.FALSE) // 
@MicronautTest // 
class HomeControllerTest {

    @Test
    void testRedirectionToSwaggerUi(@Client("/") HttpClient httpClient) {  // 
        BlockingHttpClient client = httpClient.toBlocking();
        HttpResponse<?> response = assertDoesNotThrow(() -> client.exchange("/"));
        assertEquals(HttpStatus.SEE_OTHER, response.getStatus());
        assertNotNull(response.getHeaders().get(HttpHeaders.LOCATION));
        assertEquals("/swagger-ui/index.html", response.getHeaders().get(HttpHeaders.LOCATION));
    }

    @Test
    void homeControllerIsHidden(@Client("/") HttpClient httpClient) {
        BlockingHttpClient client = httpClient.toBlocking();
        String yml = assertDoesNotThrow(() -> client.retrieve("/swagger/micronaut-guides-1.0.yml"));
        assertFalse(yml.contains("operationId: home")); // 
    }
}

1	Annotate the class with `@Property` to supply configuration to the test.
2	Annotate the class with `@MicronautTest` so the Micronaut framework will initialize the application context and the embedded server. More info.
3	Inject the `HttpClient` bean and point it to the embedded server.
4	The root endpoint is not included in the OpenAPI specification.

Testing the Application

To run the tests:

./mvnw test

Running the Application

To run the application, use the ./mvnw mn:run command, which starts the application on port 8080.

If you go to http://localhost:8080, you will see the Swagger UI visualization of the compile-time generated OpenAPI specification.

Generate a Micronaut Application Native Executable with GraalVM

We will use GraalVM, an advanced JDK with ahead-of-time Native Image compilation, to generate a native executable of this Micronaut application.

Compiling Micronaut applications ahead of time with GraalVM significantly improves startup time and reduces the memory footprint of JVM-based applications.

Note	Only Java and Kotlin projects support using GraalVM’s `native-image` tool. Groovy relies heavily on reflection, which is only partially supported by GraalVM.

GraalVM Installation

The easiest way to install GraalVM on Linux or Mac is to use SDKMan.io.

Java 25

sdk install java 25.0.2-graal

For installation on Windows, or for a manual installation on Linux or Mac, see the GraalVM Getting Started documentation.

The previous command installs Oracle GraalVM, which is free to use in production and free to redistribute, at no cost, under the GraalVM Free Terms and Conditions.

Alternatively, you can use the GraalVM Community Edition:

Java 25

sdk install java 25.0.2-graalce

Native Executable Generation

To generate a native executable using Maven, run:

./mvnw package -Dpackaging=native-image

The native executable is created in the target directory and can be run with target/micronautguide.

It is possible to customize the name of the native executable or pass additional build arguments using the Maven plugin for GraalVM Native Image building. Declare the plugin as follows:

pom.xml

<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
    <version>0.11.5</version>
    <configuration>
         
         <imageName>mn-graalvm-application</imageName>
        <buildArgs>
          
          <buildArg>-Ob</buildArg>
        </buildArgs>
    </configuration>
</plugin>

1	The native executable name will now be `mn-graalvm-application`.
2	It is possible to pass extra build arguments to `native-image`. For example, `-Ob` enables the quick build mode.

Next Steps

Explore more features with Micronaut Guides.

Help with the Micronaut Framework

The Micronaut Foundation sponsored the creation of this Guide. A variety of consulting and support services are available.

License

Note	All guides are released with an Apache License 2.0 for the code and a Creative Commons Attribution 4.0 license for the writing and media (images).