Test RESTful API of Adventuretube Microservice Using Springdoc Swagger UI

This blog outlines the full journey of integrating and testing Swagger UI for the Adventuretube microservices system using Springdoc and Spring Cloud Gateway. The integration was accomplished through three main phases:

Phase 1: Configuration of Swagger UI and OpenAPI Aggregation

Below is a brief explanation of what needs to be done at the first phase; you can see actual details here.

• Set up Springdoc in each microservice (auth-service, member-service, web-service, geo-service).

• Added the necessary dependencies for springdoc-openapi-ui.

• Configured the application.yml in each service:

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

• Gateway was configured to aggregate all services’ API docs via:

  springdoc:
    swagger-ui:
      urls:
        - name: Auth Service
          url: /auth-service/v3/api-docs
        - name: Member Service
          url: /member-service/v3/api-docs
        - name: Web Service
          url: /web-service/v3/api-docs
        - name: Geospatial Service
          url: /geo-service/v3/api-docs
  

• Swagger UI became accessible at  https://api.adventuretube.net/swagger-ui/index.html, displaying all microservices.But it was not since adventuretube has  strong access control from the gateway to each downstream microservice . so what actually happen is you will be able to see the swagger UI but it will come with security  error message and not able to bring the each micro service’s API document .

  so lets move on the second chapter to adjust this security depence .

Phase 2: Integration with Gateway Security Design

Below is a brief explanation of what needs to be done at the second phase; you can see actual details here.

• Integrated custom AuthenticationFilter in the API Gateway.

• Configured RouterValidator to whitelist /swagger-ui.*, /v3/api-docs.*, and public /auth routes.

• In Gateway’s RouteLocator, routing to /xxx-service/v3/api-docs strips the prefix and forwards to the appropriate microservice.

• In each service, Spring Security was applied via SecurityFilterChain and JwtAuthFilter, but /v3/api-docs and Swagger UI routes were allowed:

  .requestMatchers(
    "/swagger-ui.html",
    "/swagger-ui/**",
    "/v3/api-docs",
    "/v3/api-docs/**"
  ).permitAll()
  

Phase 3: Final Testing and Validation via Swagger UI

Below is a brief explanation of what needs to be done at the third phase; you can see actual details here.

• Validated each service from the unified Swagger UI.

• Verified endpoints like /auth/register, /member/storeTokens, and /geo/kafka/publish.

• Ensured CORS and forwarding issues were resolved by setting correct server-url in application.yml.

• Verified that curl commands and interactive UI use the gateway domain (https://api.adventuretube.net) instead of local IPs.

✅ Result: Fully functional Swagger UI integration, secure routing, centralized documentation, and real-time API testing across microservices.

Conclusion

The successful Swagger integration across Adventuretube microservices provides a single entry point for API exploration, testing, and validation. Through the use of Springdoc, Spring Security, and a centralized API Gateway, this setup achieves both developer productivity and production-grade security.