This guide demonstrates integrating Swagger 3 (OpenAPI) with Spring Cloud Gateway for streamlined microservice API documentation. We'll leverage Java 21, Spring Boot 3.2 , and Micronaut to create a robust and user-friendly solution.

Why Choose Swagger/OpenAPI?

Swagger, now the OpenAPI Specification (OAS), is the leading API documentation standard. Its benefits include:

• Industry Standard: Widely adopted and supported by a rich ecosystem of tools.
• Interactive Documentation: Generates user-friendly documentation allowing developers to explore and test APIs directly.
• Improved Developer Productivity: Features like code generation for SDKs and server stubs accelerate API development.
• Enhanced Collaboration: Provides a common understanding of API functionality for developers, testers, and stakeholders.
• Simplified Testing and Debugging: The Swagger UI includes a testing interface for validating API responses.
• Cross-Language Support: Integrates seamlessly across diverse technology stacks.
• Easy Integration: Simple integration with popular frameworks like Spring Boot and Micronaut.
• Automation-Friendly: Supports automation for API lifecycle management.
• Open Source with Enterprise Options: Available as a free, open-source tool with enterprise options.

Spring Cloud Gateway: The Foundation

Spring Cloud Gateway, built on Spring Framework 5, Spring Boot 2, and Project Reactor, acts as a central entry point for routing and filtering requests to your microservices.

How Spring Cloud Gateway Functions:

The diagram below illustrates Spring Cloud Gateway's operation:

Client requests are evaluated against defined routes. Matching requests are processed by a Gateway Web Handler, executing pre- and post-filters before and after request proxying.

Building the Application:

Prerequisites:

1. Java 21
2. Gradle (or Maven)
3. Spring Boot 3.2 or later
4. Understanding of Spring Cloud Gateway and Swagger
5. Micronaut

Step-by-Step Implementation:

Step 1: Create Micronaut Applications (Job, Perk, Tag Services)

Use the Micronaut Launcher ([link to launcher]) to create three Micronaut applications: job-service, perk-service, and tag-service. Select Java or Kotlin, the latest stable Micronaut version, Swagger UI, and OpenAPI as features. Use Gradle or Maven as the build tool. Each service will have a Swagger UI accessible (e.g., http://localhost:8081/swagger-ui/index.html for job-service). You can also use the CLI:

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

(Repeat for perk-service and tag-service, adjusting the package name accordingly).

Step 2: Create the Spring Boot API Gateway

Use Spring Initializr ([link to Spring Initializr]) to generate a Spring Boot project. Include the following dependencies: Spring Cloud Gateway, Spring Boot Actuator, and Spring Web.

Step 3: Integrate Swagger into the API Gateway

Add the necessary Springdoc dependencies to your pom.xml (Maven) or build.gradle (Gradle):

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")
}

Configure the application.yml to enable Swagger UI and specify the URLs for each microservice's Swagger YAML files:

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

Set the API Gateway port to 8080 in application.yml:

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

Step 4: Run the Applications

Start each of the four applications (three Micronaut services and the Spring Boot Gateway). The Gateway's Swagger UI will be accessible at http://localhost:8080/webjars/swagger-ui/index.html.

Conclusion:

This combined approach provides a powerful and well-documented microservice architecture. The Spring Cloud Gateway efficiently routes requests, while Swagger offers a centralized and interactive API documentation experience. This setup significantly improves developer productivity and collaboration. Remember to replace placeholder URLs with the actual URLs of your microservices' Swagger YAML files.

The above is the detailed content of Aggregate Microservices&# Swagger UI from an API Gateway Using Spring API Gateway and Micronaut. For more information, please follow other related articles on the PHP Chinese website!