Swagger를 사용해 API 설계 문서 작성하기

지니·2025년 4월 18일

REST API Swagger

Spring

목록 보기

12/13

1. Swagger란?

API 문서를 자동으로 만들어주는 라이브러리이다. Swagger는 단순한 문서 뿐만 아니라 매개변수를 넣어가면서 실행 할 수 있다.

🔍 좀 더 자세하기 설명하면
예를 들어, 우리가 spring으로 어플리케이션을 제작했고, 여기엔 유저 리스트를 가져오는 기능과 게시글을 등록하는 기능이 있다고 하자

/api/users로 유저 리스트를 가져오기
/api/posts로 게시글을 등록하기

라는 기능이 있다고 생각하자. 이 때, 이런 것들을 누가, 어떻게 쓰는지 문서화 하고 이것들을 테스트도 해야 한다. 이 때, Swagger가 자동으로 이런 작업을 도와주는 것이다.

2. Swagger 사용하는 방법

2-1. build.gradle파일에 의존성 추가하기

build.gradle에 springdoc-openapi를 추가해주면 된다.

⚠️ 주의할 점
버전이 잘 맞는지 꼭 확인하기
: 처음에 springdoc-openapi 2.2.0 버전을 사용했다. 그런데 계속 fetch error가 발생했다.

내가 사용하는 spring boot 3.4.4 버전에 맞는 버전을 찾아서 사용했다. 혹시나 오류가 발생한다면 권장하고 있는 버전을 잘 매치해서 사용하고 있는지 한 번 확인해보면 좋다.
공식문서에서 답변한 부분 https://springdoc.org/faq.html#_what_is_the_compatibility_matrix_of_springdoc_openapi_with_spring_boot

2-2. yml 파일에 설정하기

packages-to-scan : 어느 패키지에서 API를 찾을지 알려주는 설절으로 이 패키지 안에 있는 Controller 클래스만 Swagger 문서에 나타난다.
default-consumes-media-type : 요청에서 어떤 타입의 데이터를 받을지 설정하는 것
default-produces-media-type : 응답에서 어떤 타입의 데이터를 응답할지 설정하는 것

springdoc:
  packages-to-scan: com.dbwls.restapi.section05
  // json 형식의 데이터를 UTF-8로 요청
  default-consumes-media-type: application/json;charset=UTF-8
  // json 형식의 데이터를 UTF-8로 응답
  default-produces-media-type: application/json;charset=UTF-8

2-3. Config 설정하기

Info : Swagger UI 상단에 표시될 정보를 설정하는 객체
OpenAPI : Swagger 에서 사용하는 스펙을 설정하는 객체

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(swaggerInfo());
    }

    private Info swaggerInfo() {
        return new Info()
                .title("dbwls API") // 문서 제목
                .description("SpringBoot Swagger 연동 테스트") // 문서에 대한 설명
                .version("1.0.0"); // 문서 버전
    }

}