Aggregate Microservices' Swagger UI from an API Gateway Using Spring API Gateway and Micronaut

In today's fast-paced microservices landscape, efficient API management and documentation are essential. Swagger, now recognized as OpenAPI, has established itself as the industry standard for API documentation. At the same time, Spring Cloud Gateway has gained popularity as a powerful solution for routing and filtering requests across microservices. This guide delves into integrating Swagger 3 with Spring Cloud Gateway to deliver a streamlined API documentation experience.

Why Swagger?

Swagger, now part of the OpenAPI Specification (OAS), is a powerful and widely adopted tool for designing, documenting, and interacting with APIs. Here’s why Swagger stands out:

• Industry Standard
  Swagger/OpenAPI is the most recognized specification for API documentation and is supported by a vast ecosystem of tools and frameworks.

• Comprehensive API Documentation
  Swagger generates interactive, user-friendly documentation that allows developers to explore and test APIs directly from the documentation itself.

• Developer Productivity
  It simplifies API development with features like code generation for client SDKs and server stubs, reducing the time needed to implement APIs.

• Enhanced Collaboration
  Swagger bridges the gap between developers, testers, and stakeholders by providing a clear, shared understanding of API functionality.

• Improved Testing and Debugging
  The Swagger UI offers a built-in testing interface, making it easy to validate API responses and identify issues during development.

• Cross-Language Support
  With broad language compatibility, Swagger fits seamlessly into diverse tech stacks, enabling integration across multiple platforms.

• Ease of Integration
  Swagger tools are easy to integrate with popular frameworks like Spring Boot, Micronaut, and Express.js, ensuring minimal setup effort.

• Automation-Friendly
  It supports automation for API lifecycle processes, including testing, CI/CD pipelines, and compliance validation.

• Open Source with Enterprise Options
  Swagger is free and open source, with optional enterprise-level solutions for more advanced use cases.

Spring Cloud Gateway

Spring Cloud Gateway is a robust library built on Spring Framework 5, Spring Boot 2, and Project Reactor. It serves as a unified entry point for applications, offering a streamlined and efficient solution for routing and filtering requests to multiple microservices.

How It Works

The following diagram provides a high-level overview of how Spring Cloud Gateway works:

When clients send requests to Spring Cloud Gateway, the Gateway Handler Mapping evaluates whether the request matches a defined route. If a match is found, the request is forwarded to the Gateway Web Handler. This handler processes the request through a specific filter chain. Filters are designed to execute logic in two stages: before (“pre”) and after (“post”) the proxy request. Initially, all pre-filter logic is executed, followed by the proxying of the request. Once the proxy request is complete, the post-filter logic is executed.

What we are building

Prerequisites

1. Java 21
2. Gradle
3. Spring Boot 3.2 or later
4. Basic knowledge of Spring Cloud Gateway and Swagger
5. Micronaut

Step 1

Create the First Micronaut Application (Job Service)
Go to the Micronaut Launcher website:

Configure the Application:

• Project Name: product-service
• Language: Java or Kotlin (Choose according to your preference)
• Micronaut Version: Select the latest stable version

Features:

• Select Swagger UI and OpenAPI
• Build Tool: Maven or Gradle (Choose according to your preference)

• Click on "Generate Project": This will generate a .zip file with the initial project setup.

• Extract the zip file and open it in your IDE (e.g., IntelliJ IDEA).

• Run the application: After the setup, run the application using the following command:
  

./mvnw mn:run  # for Maven
./gradlew run  # for Gradle

Or Using CLI

mn create-app --build=gradle_kotlin --jdk=21 --lang=java --test=junit --features=openapi,swagger-ui dev.job.job

The swagger UI URL - http://localhost:8081/swagger-ui/index.html

Step 2

Create the second Micronaut Application (Perk Service)
Go to the Micronaut Launcher website:

Configure the Application:

• Project Name: product-service
• Language: Java or Kotlin (Choose according to your preference)
• Micronaut Version: Select the latest stable version

Features:

• Select Swagger UI and OpenAPI
• Build Tool: Maven or Gradle (Choose according to your preference)

• Click on "Generate Project": This will generate a .zip file with the initial project setup.

• Extract the zip file and open it in your IDE (e.g., IntelliJ IDEA).

• Run the application: After the setup, run the application using the following command:
  

./mvnw mn:run  # for Maven
./gradlew run  # for Gradle

Or Using CLI

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

The swagger UI URL - http://localhost:8082/swagger-ui/index.html

Step 3

Create the third Micronaut Application (Tag Service)
Go to the Micronaut Launcher website:

Configure the Application:

• Project Name: product-service
• Language: Java or Kotlin (Choose according to your preference)
• Micronaut Version: Select the latest stable version

Features:

• Select Swagger UI and OpenAPI
• Build Tool: Maven or Gradle (Choose according to your preference)

• Click on "Generate Project": This will generate a .zip file with the initial project setup.

• Extract the zip file and open it in your IDE (e.g., IntelliJ IDEA).

• Run the application: After the setup, run the application using the following command:
  

./mvnw mn:run  # for Maven
./gradlew run  # for Gradle

Or Using CLI

mn create-app --build=gradle_kotlin --jdk=21 --lang=java --test=junit --features=openapi,swagger-ui dev.tag.tag

The swagger UI URL - http://localhost:8083/swagger-ui/index.html

Step 4

Head over to Spring Initializr, the go-to dependencies for generating Spring Boot projects. Here's how to configure your API gateway project:

Project: Maven or Gradle (your choice)
Language: Java

Dependencies:

• Spring Cloud Gateway: The core library for building your gateway
• Spring Boot Actuator: For monitoring and insights
• Spring Web: To enable web functionalities

Click Generate to download your project as a .zip file. Extract it and open it in your favorite IDE (e.g., IntelliJ IDEA, Eclipse, or VS Code).

Step 5

To make your Spring API Gateway not only functional but also developer-friendly, integrating Swagger UI and OpenAPI is a game changer. Swagger provides an interactive interface for exploring and testing your APIs, making it easier for developers to understand and use your services.

dependencies {
    implementation("org.springframework.cloud:spring-cloud-starter-gateway")
    implementation("org.springdoc:springdoc-openapi-starter-webmvc-api:2.8.3")
    implementation("org.springdoc:springdoc-openapi-starter-webflux-ui:2.8.3")

}

To set the port of your API Gateway project to 8080, you can update the application.yml file as follows:

server:
  port: 8080
spring:
  application:
    name: web-api-gateway

To enable Swagger UI and documentation in your Spring API Gateway project, use the following configuration in the application.yml file:

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    config-url: /v3/api-docs/swagger-config

To configure the Swagger YAML files of other services so that the API Gateway can display them, you need to reference the exposed Swagger YAML URLs of each service in the springdoc.swagger-ui.urls section. Here's an example configuration:

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    config-url: /v3/api-docs/swagger-config
    urls:
      - name: Job Service
        url: http://localhost:8081/swagger/job-service-0.0.yml

      - name: Perk Service
        url: http://localhost:8082/swagger/perk-0.0.yml

      - name: Tag Service
        url: http://localhost:8083/swagger/tag-0.0.yml

      - name: Additional Requirement Service
        url: http://localhost:8084/swagger/additional-requirement-0.0.yml

Api gateway swagger URL http://localhost:8080/webjars/swagger-ui/index.html

Running the Applications

Gateway: on port 8080.
Job Service: on port 8081.
Tag Service: on port 8082.
Perk Service: on port 8083.

Conclusion

Combining Swagger 3 with Spring Cloud Gateway, powered by Java 21 and Spring Boot 3.2, offers a robust solution for managing and documenting microservices. This integration not only streamlines request routing and filtering but also ensures your APIs are clearly documented and easily accessible. By following this guide, you can elevate your microservice architecture with an efficient API gateway and detailed, user-friendly documentation.