Test RESTful API of Adventuretube Microservice Using Springdoc Swagger UI

This blog outlines the full journey of integrating, adjusting, and testing Swagger UI for the Adventuretube microservices system using Springdoc, Spring Cloud Gateway, and finally with Postman3. The work is structured into five major phases:

Benefits of Full Swagger UI and Postman Integration

With these processes, you will have different aspects of benefit like below.

1. As a producer of API:

Your documentation will be exposed with a very clean convention that you may not even need to create separate documentation to explain your API.
You are also able to test your own API partially or fully automated depending on the process you’ve made. If you utilize Jenkins and n8n AI agent together (which I haven’t seen yet in examples online), it could be an enormous time saver with a strong test process in your CD/CI pipeline.
You will have a centralized single place where all your APIs are documented and visible, helping you easily manage, update existing APIs, and design new APIs consistently and efficiently.

2. As a consumer of API:

You will be able to access and understand the actual usage of the API much easier and faster, and even test it immediately to give you an instant start to work.
You will have realistic example data available directly in the API docs, making it much simpler to craft correct requests without guessing formats.
You can easily import the API into Postman collections using real examples, making early validation of API behaviors fast without needing backend development knowledge.

✅ And at the end of this process:
No matter how perfectly you build an API, if it’s not easily accessible, testable, and understandable, there is no true point in building it.

This setup transforms your API from a theoretical backend resource into a real-world usable and valuable service.

Phase 1: Setup Swagger UI and OpenAPI Aggregation

Configured Springdoc in each microservice (auth-service, member-service, web-service, geo-service) using a centralized configuration managed by Spring Cloud Config.
Instead of configuring application.yml separately in each microservice, added the following settings in the centralized config files (config-service/src/main/resources/config/*.yml):

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

✅ This approach ensures centralized management of Swagger and Springdoc properties for all services, minimizing duplication and making future updates easier.

In the Gateway Service, configured multiple sub-service documentation endpoints under application.yml to aggregate all APIs into the central Swagger UI:

springdoc:
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    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

✅ This configuration allows Swagger UI at the API Gateway to display all sub-service APIs together in one portal:
https://api.adventuretube.net/swagger-ui/index.html

You can verify if Spring Cloud Config correctly applied the settings by checking:
🔹 https://config.adventuretube.net/auth-service/native (as shown in the screenshot)
🔹 Validate that springdoc.api-docs.path and springdoc.swagger-ui.path are properly loaded.

✅ Result:

Swagger UI is available centrally.
All microservices’ API docs are exposed via the Gateway.
Configuration is controlled from one place (Spring Config Server).

Phase 2: Adjust Gateway and Microservice Security for Swagger Access

Integrated a global AuthenticationFilter at the Gateway.
Whitelisted Swagger UI paths and /v3/api-docs/** using RouterValidator.
Updated Spring Security in each service to permit access to Swagger paths.
Gateway RouteLocator correctly routed API docs without security blocking.

✅ Result: Swagger UI loaded without errors but still showed internal IP addresses.

These are brief explanations for what you have to do but don’t include any explanation of why. So in order to understand why, you need to understand the Spring Security mechanism that is applied in Adventuretube. 👉 Check out the detailed Spring Security blog here.

Phase 3: Centralize Swagger UI Access via API Gateway

Problem: Swagger UI listed API servers using internal IPs and ports.
Solution: Added @OpenAPIDefinition in each microservice to override server URL:

@OpenAPIDefinition(
    servers = {
        @Server(url = "https://api.adventuretube.net", description = "Adventuretube API Gateway")
    }
)

✅ Result: All APIs now routed through https://api.adventuretube.net without IP exposure.

Phase 4: Create Realistic API Examples for Instant Testing

Added @ExampleObject to all major API endpoints.
Example structure for signup API:

@Operation(
    summary = "Signup user",
    requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(
        content = @Content(
            mediaType = "application/json",
            examples = @ExampleObject(
                name = "Signup Example",
                value = """
                {
                  "googleIdToken": "<Google ID Token>",
                  "refreshToken": "ref-token",
                  "email": "strider@gmail.com",
                  "password": "123456",
                  "username": "striderlee",
                  "role": "USER",
                  "channelId": "UC_x5XG..."
                }
                """
            )
        )
    )
)

✅ Result: APIs were immediately testable via Swagger UI “Try it out” with full request examples.

Phase 5: Make OpenAPI Docs Fully Importable into Postman 3

Problem: Postman 3 could not import /v3/api-docs because title, version, and description were missing.
Solution: Added a SwaggerConfig class in each service:

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("AdventureTube Auth API")
                .version("1.0.0")
                .description("API documentation for AdventureTube authentication microservice."));
    }
}

Each microservice now exposes a valid OpenAPI 3.0 JSON with proper title, version, and description.
To import into Postman 3:
- Use the URL like https://api.adventuretube.net/auth-service/v3/api-docs.
- In import settings, set Parameter Generation to Example instead of Schema, so Postman automatically uses your defined realistic examples.

✅ Result: Full Postman 3 collections ready with real-world request bodies, enabling fast manual or automated API tests.

Next Step: Toward Full RESTful API Test Automation with Jenkins + n8n AI

Now that Swagger UI and Postman testing are fully functional, the next phase focuses on complete CI/CD and automated testing:

Use Jenkins on the Raspberry Pi server to detect Git merges into main.
Trigger a pipeline:
- Clean and repackage all microservice JARs.
- Build and deploy Docker containers.
Use n8n AI Automation:
- Automatically trigger Postman-based API tests.
- Decode JWT tokens and validate protected endpoints.
Report results through Slack, Email, or custom dashboards.

✅ Goal: Full microservice RESTful API automation — every critical endpoint validated automatically after code changes!