5.4 Swagger 사용하기

김찬미·2024년 6월 10일

[Book] 스프링 부트 핵심 가이드

목록 보기

15/45

Swagger란?

API를 개발하면 명세를 관리해야 한다. 명세란 해당 API가 어떤 로직을 수행하는지 설명하고 이 로직을 수행하기 위해 어떤 값을 요청하며, 이에 따른 응답값으로는 무엇을 받을 수 있는지를 정리한 자료이다.

API는 개발 과정에서 계속 변경되므로 작성한 명세 문서도 주기적인 업데이트가 필요하다. 또한 명세 작업은 번거롭고 시간 또한 오래 걸린다. 이 같은 문제를 해결하기 위해 등장한 것이 바로 Swagger라는 오픈소스 프로젝트이다.

Swagger를 사용하기 위한 단계

1) 의존성 추가

1-1) maven일 때 (pom.xml 파일에 추가)

    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.9.2</version>
    </dependency>

    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.9.2</version>
    </dependency>
  </dependencies>

1-2) gradle일 때 (build.gradle 파일에 추가)

dependencies {
    implementation 'io.springfox:springfox-swagger2:2.9.2'
    implementation 'io.springfox:springfox-swagger-ui:2.9.2'
}

2) Swagger 설정 코드 작성

의존성을 추가했으면 Swagger와 관련된 설정 코드를 작성해야 한다. 이 클래스는 설정(Configuration)에 관한 클래스로, config 패키지를 생성한 후 그 안에 작성하는 것이 좋다.

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            // Swagger에서 스캔할 패키지 범위, 하위 패키지와 클래스를 모두 스캔해 문서 생성
            .apis(RequestHandlerSelectors.basePackage("com.springboot.api"))
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("Spring Boot Open API Test with Swagger")
            .description("설명 부분")
            .version("1.0.0")
            .build();
    }
}

이 설정이 적용되면, Spring Boot 애플리케이션이 실행될 때 Swagger가 활성화되고, http://localhost:8080/swagger-ui.html URL에서 Swagger UI를 통해 API 문서를 확인할 수 있다.

3) Controller에 있는 Method 세부 내용 설정

Swagger를 더 잘 활용하기 위해 이번에 작성한 API 중 @RequestParam을 활용한 GET 메서드에 대한 명세의 세부 내용을 설정해보자. GetController(전 게시물 참고)에 작성한 메서드를 아래와 같이 수정해보자.

@ApiOperation(value = "GET 메소드 예제", notes = "@RequestParam을 활용한 GET Method")
@GetMapping(value = "/request1")
public String getRequestParam1(
    @ApiParam(value = "이름", required = true) @RequestParam String name,
    @ApiParam(value = "이메일", required = true) @RequestParam String email,
    @ApiParam(value = "회사", required = true) @RequestParam String organization) {
    return name + " " + email + " " + organization;
}

Swagger 관련 어노테이션

@ApiOperation: 대상 API의 설명을 작성하기 위한 어노테이션이다.
@ApiParam: 매개변수에 대한 설명 및 설정을 위한 어노테이션이다. 메서드의 매개변수뿐 아니라 DTO 객체를 매개변수로 사용할 경우 DTO 클래스 내의 매개변수에도 정의할 수 있다.

위와 같이 설정한 후 해당 API 명세를 Swagger 페이지에서 살펴보면 아래와 같다.

Swagger 페이지

Swagger 페이지의 API 명세

@ApiOperation에 작성한 내용은 그림 상단에 표기되고 @ApiParam에 정의한 내용은 아래 'Parameters' 영역의 'Description' 항목에 추가되었다. 위 그림처럼 Swagger는 해당 API가 무엇인지 설명하고 어떤 값이 필요한지 한 눈에 보여준다.

Swagger에서는 API 명세 뿐만 아니라 직접 통신도 시도할 수 있다. 위 화면에서 [Try it out] 버튼을 클릭하면 아래와 같은 화면이 나타난다.