[spring boot] - Swagger로 API 문서화하기

💁🏻‍♀️ 나의 상황

현직 개발자에게 Swagger UI를 현직에서도 많이 사용한다는 정보를 듣게 되어서, 이번 팀 프로젝트에도 적용해 보기로 마음먹었다!

 

1. Swagger란 무엇인가?

Swagger는 RESTful API를 설계, 구축, 문서화 및 소비하기 위한 오픈 소스 프레임워크이다.

Swagger는 API가 어떻게 작동하는지에 대한 명확한 이해를 제공하며, 개발자와 클라이언트 간의 의사소통을 개선하여 API의 품질을 높이는 데 도움을 준다.

 

2. Spring Boot에서 Swagger 설정하기

2.1. 의존성 추가

먼저 build.gradle 파일에 Swagger 관련 의존성을 추가한다.

Spring Boot 3.x 버전부터는 springdoc-openapi 라이브러리를 사용하는 것이 권장된다.

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

 

2.2. Swagger 설정 클래스 작성

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {
        @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .components(new Components())
                .info(apiInfo());
    }

    private Info apiInfo() {
        return new Info()
                .title("Spring Boot REST API Specifications")
                .description("Specification")
                .version("1.0.0");
    }
}

 

2.3. Swagger UI 접근

애플리케이션을 실행한 후, 브라우저에서 http://localhost:8080/swagger-ui.html로 접속하면 Swagger UI를 통해 API 문서를 볼 수 있다. 이 화면에서 각 API의 엔드포인트와 설명, 요청/응답 예제를 확인할 수 있다.

 

실제 팀 프로젝트에 적용된 Swagger UI