Swagger UI Intergation vis Spring Cloud Gateway #1

🧭 Overview

This guide outlines the essential step-by-step setup for integrating Swagger 3 (OpenAPI 3) in a Spring Cloud microservices architecture.

In my adventuretube microserice. It does require two separate two-phase of integration 

🛠️ Two-Phase Integration Overview

🔹 Step 1: Swagger Configuration for Each Service

Each microservice is configured with Springdoc OpenAPI to generate Swagger documentation. These are then aggregated through the Gateway using predefined routes and exposed under a unified Swagger UI.

🔹 Step 2: Security Configuration for Microservices

After setting up the gateway forwarding, security configurations within each microservice must be adjusted to permit access to documentation endpoints (/v3/api-docs, /swagger-ui/**) while still protecting business logic routes with JWT-based filters.

✅ Step 1: Essential Swagger Configuration for Each Microservice

Each microservice must be individually configured to expose its OpenAPI documentation.

🔧 Dependencies (Add to each microservice pom.xml)

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>${spring-doc.version}</version>
</dependency>

✅ Use webmvc-ui because individual microservices are based on Spring MVC.

🛠 Configuration via Spring Cloud Config (config-service)

Define Swagger config per microservice using Git-backed xxx-service.yml files.

Example for any service (e.g. web-service.yml):

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html

📝 These files should be located under: config-service/src/main/resources/config/

🔍 Validate Remote Config

To ensure your microservice has correctly loaded the new config from Git, call the Spring Cloud Config endpoint:

GET http://192.168.1.105:9297/web-service/default

• Replace web-service with the name of your service.

• This confirms that the Swagger-related config has been successfully fetched.

🧪 Result

After restarting each service:

• OpenAPI JSON: http://localhost:<port>/v3/api-docs

• Swagger UI: http://localhost:<port>/swagger-ui.html

✅ Step 2: Essential API Gateway Configuration for Swagger Routing

The API Gateway acts as a reverse proxy and exposes Swagger documentation from all microservices in a unified interface.

🔧 Dependencies (Add to gateway-service/pom.xml)

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
</dependency>

⚠️ Important: Use webflux-ui in the gateway because Spring Cloud Gateway is built on Spring WebFlux (reactive stack). Do not use webmvc-ui here.

🧩 Parent POM Best Practice

To support any future WebFlux-based modules (e.g. gateways, reactive APIs), define the WebFlux Swagger dependency centrally:

In adventuretube-microservice/pom.xml:

<dependencyManagement>
  <dependencies>
    <!-- already defined webmvc-ui -->
    <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
      <version>${spring-doc.version}</version>
    </dependency>
  </dependencies>
</dependencyManagement>

Then, in any WebFlux-based module:

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
</dependency>

✅ Keeps version management centralized and avoids mismatches.

🌐 Routing Configuration (GatewayConfig.java)

Define Swagger routes separately (without filters) in your RouteLocatorBuilder:

.route("auth-docs", r -> r.path("/auth/v3/api-docs").uri("lb://auth-service"))
.route("member-docs", r -> r.path("/member/v3/api-docs").uri("lb://member-service"))
.route("web-docs", r -> r.path("/web/v3/api-docs").uri("lb://web-service"))
.route("geo-docs", r -> r.path("/geo/v3/api-docs").uri("lb://geospatial-service"))

🚫 Do not apply auth filters to these routes so that Swagger UI can fetch API docs.

📘 Swagger UI Aggregation (application.yml in gateway)

springdoc:
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    urls:
      - name: Auth Service
        url: /auth/v3/api-docs
      - name: Member Service
        url: /member/v3/api-docs
      - name: Web Service
        url: /web/v3/api-docs
      - name: Geospatial Service
        url: /geo/v3/api-docs
  api-docs:
    enabled: true

✅ Final Result

Access the Gateway Swagger UI at:

http://localhost:8080/swagger-ui.html

This shows a centralized UI for all services’ API documentation.

📌 Summary (Essential Setup Only)

✏️ This guide includes only the essential setup. Extra enhancements (metadata, custom OpenAPI beans, security, etc.) can be added after verifying base functionality.