Spring Boot(Kotlin) — 4편. Swagger(OpenAPI) 설정 가이드

📚 Spring Boot(Kotlin) 서버 기본 셋팅 — 시리즈 안내

1. 왜 멀티 모듈 구조인가? (아키텍처 철학 & 전체 설계 편)
2. API Response 포맷 설계
3. 글로벌 예외 처리(GlobalExceptionHandler)
4. Swagger(OpenAPI) 설정 ← 현재 글
5. Security(JWT) 기본 골격
6. JWT TokenProvider
7. Redis 설정
8. Validation 설정
9. Logging + MDC(traceId)
10. application.yml 프로필 분리 (local/dev/prod)
11. 멀티모듈 + JPA 기본 구조 정리
12. 완성된 프로젝트 템플릿 git 공유

---

📌 Swagger(OpenAPI) 설정은 왜 필요할까?

백엔드 API 서버를 개발하면 가장 먼저 마주하는 문제가 있습니다.

- 프론트/앱/QA 팀과 API 규격을 어떻게 공유할까?
- 요청/응답 구조를 매번 문서로 설명해야 할까?
- JWT 인증이 필요한 API는 어떻게 테스트하지?

이 문제를 해결하는 가장 대표적인 도구가 Swagger(OpenAPI)입니다. 브라우저에서 바로 API를 테스트하고 문서화를 자동으로 생성해주는 강력한 도구입니다.

📌 SwaggerConfig는 왜 API 모듈에 둘까?

Swagger는 외부와 직접 연결되는 API 계층의 기능입니다.

- Application 모듈: 비즈니스 로직, 도메인 로직 - API 모듈: 컨트롤러, Request/Response 모델, Swagger, 예외 처리

따라서 Swagger 설정은 API 레이어에 존재해야 한다고 생각하고, 외부 호출자가 사용하는 API 목록을 자동으로 표현하는 역할을 담당합니다.

📌 필요한 Dependency

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

✔ Spring Boot 3.x 환경에서 사용하는 springdoc 최신 버전
✔ /swagger-ui.html 또는 /swagger-ui/index.html 로 접근 가능

📌 SwaggerConfig 전체 코드

예시 프로젝트 이름은 Example API로 변경했습니다.

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

 

 

📌 코드 상세 설명

1️⃣ @Configuration + @Bean

Spring이 관리하는 Bean으로 등록해 Swagger OpenAPI 인스턴스를 생성한다.

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

API 제목, 설명, 버전을 설정하는 메타데이터 구성

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

로컬/운영 환경에서 공통 prefix 사용 시 Swagger가 자동 인식하도록 설정 (예: /api/v1 같은 prefix도 여기서 지정 가능)

4️⃣ JWT SecurityScheme 등록

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

Swagger UI 상단에 "Authorize" 버튼이 생기고 여기에 JWT Access Token을 넣으면 모든 API 호출에 Authorization 헤더가 자동 추가됨.

5️⃣ .addSecurityItem(SecurityRequirement())

Swagger UI에서 모든 API가 JWT 인증을 기본적으로 사용하도록 지정한다.

📌 JWT를 Swagger에서 지원

우리 서버는 앞으로 JWT 기반 인증을 사용할 예정이다. 따라서 API 문서를 보거나 테스트할 때도 JWT를 쉽게 입력할 수 있다.

✔ Authorization 헤더 자동 설정 ✔ Bearer 토큰 규격 자동 적용 ✔ 인증이 필요한 API 테스트가 매우 쉬워짐

JWT 인증 구조는 이후 시리즈(Security → JWT TokenProvider)에서 자세히 다룰 예정이다.

📌 Swagger 적용 후 URL

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

서버 실행 후 위 URL에 접속하면 자동으로 API 문서가 생성되어 보인다.

📌 결론

Swagger(OpenAPI) 설정을 추천합니다.

✔ API 문서 자동화
✔ 팀 협업 효율 증가
✔ 테스트 편의성 향상
✔ JWT 인증 지원
✔ API 모듈 구조와 책임에 완벽히 부합

📌 다음 편 예고

5편 — Security(JWT) 기본 골격
JWT 기반 인증 구조의 기본 틀을 소개할 예정이다.

 

https://jaemoi8.tistory.com/36

⚠️ Spring Boot(Kotlin) — 5편. Security(JWT) 설정