Spring Boot (Kotlin) — ep.4 Swagger (OpenAPI) Configuration

📚 Spring Boot(Kotlin) Server Setup — Series Overview

1. Why Multi-Module Architecture? (Architecture Philosophy & System Design)
2. API Response Format Design
3. Global Exception Handling (GlobalExceptionHandler)
4. Swagger(OpenAPI) Configuration ← You are here
5. Security(JWT) Core Structure
6. JWT TokenProvider
7. Redis Configuration
8. Validation Setup
9. Logging + MDC(traceId)
10. application.yml Profile Separation (local/dev/prod)
11. Multi-Module + JPA Base Structure
12. Final Project Template git share

---

📌 Why Do We Need Swagger(OpenAPI)?

When developing a backend API server, we face some common challenges:

- How do we share API specifications with frontend/mobile/QA teams?
- Do we need to manually explain request/response structures every time?
- How do we easily test APIs that require JWT authentication?

The most widely used solution to these problems is Swagger(OpenAPI). It provides automatically generated API documentation and allows you to test APIs directly from the browser.

📌 Why Is SwaggerConfig Placed in the API Module?

Swagger belongs to the API layer, which is responsible for external interaction.

- Application Module: business logic, domain rules
- API Module: controllers, request/response models, Swagger, exception handling

Therefore, Swagger configuration naturally belongs in the API module, where external clients access and browse the API list.

📌 Required Dependency

implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0")

✔ Latest springdoc version for Spring Boot 3.x
✔ Access via /swagger-ui.html or /swagger-ui/index.html

📌 Full SwaggerConfig Code

Project name has been changed to Example API for demonstration.

@Configuration
class SwaggerConfig {

    @Bean
    fun openApi(): OpenAPI {
        return OpenAPI()
            .info(apiInfo())
            .servers(listOf(Server().url("/")))
            .components(components())
            .addSecurityItem(SecurityRequirement().addList("access-token"))
    }

    private fun apiInfo(): Info {
        return Info()
            .title("Example API")
            .description("Example API Documentation")
            .version("v1")
    }

    private fun components(): Components {
        val securityScheme = SecurityScheme()
            .type(SecurityScheme.Type.HTTP)
            .scheme("bearer")
            .bearerFormat("JWT")
            .`in`(SecurityScheme.In.HEADER)
            .name("Authorization")

        return Components().addSecuritySchemes("access-token", securityScheme)
    }
}

📌 Code Breakdown

1️⃣ @Configuration + @Bean

Registers Swagger OpenAPI as a Spring-managed Bean.

2️⃣ OpenAPI().info(apiInfo())

Defines metadata such as API title, description, and version.

3️⃣ .servers(listOf(Server().url("/")))

Allows Swagger to recognize server URL prefixes (e.g., /api/v1) across environments.

4️⃣ JWT SecurityScheme

SecurityScheme()
    .type(HTTP)
    .scheme("bearer")
    .bearerFormat("JWT")

Adds an "Authorize" button in Swagger UI so you can input a JWT Access Token. Swagger then automatically attaches the token to all API calls.

5️⃣ .addSecurityItem(SecurityRequirement())

Configures Swagger UI so that all APIs use JWT authentication by default.

📌 Using JWT Inside Swagger

This server uses JWT-based authentication. Swagger supports this seamlessly.

✔ Authorization header auto-applied
✔ Bearer token format enforced
✔ Makes testing secure APIs extremely convenient

JWT internals will be explored more deeply in upcoming chapters (Security → JWT TokenProvider).

📌 Swagger URL

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

After running the server, this URL displays your automatically generated API documentation.

📌 Conclusion

Swagger(OpenAPI) configuration is highly recommended.

✔ Automated API documentation
✔ Improved team collaboration
✔ Easier API testing
✔ Built-in JWT support
✔ Perfectly aligned with API module responsibilities

📌 Next Episode

Episode 5 — Security(JWT) Core Structure
We’ll explore the baseline structure for JWT-based authentication.

 

https://jaemoi8.tistory.com/37

Spring Boot (Kotlin) — ep.5 Building the Core Security Architecture with JWT in Spring Boot