Spring Boot에 Swagger(Springdoc OpenAPI) 적용하기

dev.hyjang·2025년 7월 21일

간단한 CRUD 백엔드 프로젝트에 API 문서를 자동 생성해주는 Swagger를 적용해보았습니다.
Spring Boot 3.x에서는 springdoc-openapi를 사용하는 것이 공식적으로 권장됩니다.

🔧 사용하는 기술 스택

Java 17
Spring Boot 3.5.x
Gradle
H2 Database
MyBatis
Springdoc OpenAPI (Swagger)

🚀 Springdoc OpenAPI 의존성 추가

build.gradle 파일에 아래 의존성을 추가합니다:

dependencies {
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'
}

✅ 의존성 추가 후에는 Gradle 프로젝트를 리프레시하거나 빌드해줘야 합니다.

🧩 Swagger 설정 (선택)

Swagger 문서의 제목, 설명 등을 직접 설정하고 싶다면 아래처럼 Config 클래스를 만들어줍니다:

package com.ccp.simple.controller;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("회원 관리 API")
                        .description("Spring Boot + MyBatis 기반 회원관리 시스템 API 문서")
                        .version("v1.0"));
    }
}

✅ 이 설정은 필수는 아니며, 생략해도 기본 UI는 잘 작동합니다.

🌐 Swagger UI 접속 방법

Spring Boot 앱을 실행한 후 아래 URL로 접속하면 Swagger UI를 확인할 수 있습니다.
http://localhost:8080/swagger-ui/index.html
참고) /v3/api-docs 경로는 Swagger가 내부적으로 사용하는 JSON 문서입니다.