[250429] Spring Boot + Swagger로 API 문서 자동화

👩🏻‍💻📝

[250429] Spring Boot + Swagger로 API 문서 자동화

_silver 2025. 4. 29. 21:34

👩🏻‍💻 오늘 목표 👩🏻‍💻

Spring Boot 프로젝트에 Swagger(OpenAPI 3) 설정 추가하여 API 문서를 자동화한다.

Swagger를 설정하면 서버 코드만으로도 API 문서를 쉽게 관리할 수 있고,

프론트엔드와 협업 시 API 스펙 공유 및 테스트가 편리해진다.

1. build.gradle 의존성 추가

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

2. application.properties 설정

# Swagger 접속 URL 설정 (기본값이지만 명시적으로 선언)
springdoc.swagger-ui.path=/swagger-ui.html

3. 패키지 구조

src
└── main
    └── java
        └── global
            └── config
                └── SwaggerConfig.java

☑️ global.config는 공통 설정(Spring Security, CORS, Swagger 등)을 모아두는 패키지로 구성했다.

4. SwaggerConfig 클래스 생성

package global.config;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {

		// 연락처 정보
        Contact contact = new Contact()
                .name("Baek Eunyeong")
                .email("beunyeong.b@gmail.com");

		// License 정보
        License license = new License()
                .name("Cookbot License")
                .url("https://github 주소 추가 예정")
                .url("배포 주소 추가 예정");

		// API 문서 정보(프로젝트 제목, 프로젝트 설명, Contact 및 License 정보 연결)
        Info info = new Info()
                .version("v1.0")
                .title("Cookbot API")
                .description("추후 프로젝트 설명 추가 예정")
                .contact(contact)
                .license(license);

        final String securityScheme = "bearerAuth";

        return new OpenAPI()
                .info(info)
                // 전체 API에 인증 방식 적용 (SecurityRequirement 등록)
                .addSecurityItem(new SecurityRequirement().addList(securityScheme))
                .components(new Components()
                
                		// JWT 기반 인증 설정 추가
                        .addSecuritySchemes(securityScheme, new SecurityScheme()
                                .name(securityScheme)
                                .type(SecurityScheme.Type.HTTP)
                                .scheme("bearer")
                                .bearerFormat("JWT")));

    }
}

5. Swagger URL 접속

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

6. Swagger 도입 전 후 비교

Before	After
Notion으로 API 하나하나 직접 입력	Swagger UI로 문서 자동화
API 수정시 문서를 각각 수정	코드 수정시 자동으로 반영
테스트시 Posman 따로 사용	Swagger에서 바로 테스트 가능
상태코드, 설명, 인증 직접 타이핑	어노테이션 기반으로 자동으로 노출

7. 참고 자료