[Spring] REST API를 명세하는 방법 - Swagger

스프링에서 사용되는 대표적인 REST API 명세 도구는 Swagger와 Spring Rest Docs이다. 이 둘 중 Swagger에 대해 알아보자. 

 

우린 API를 개발하면 그것을 명세화하여 관리할 필요가 있다. 여기서 명세란 API가 어떤 로직을 수행하는지 설명하고 이 로직을 수행하기 위해 어떤 값을 요청하고, 이에 따른 응답값으로 무엇을 받을지를 정리한 자료를 의미한다.

 

이러한 API 명세 작업을 개발 중 변경사항을 지속적으로 업데이트가 필요하다. 이 작업은 매우 번거롭고 시간 소모가 일어난다. 이 같은 문제를 해결하기 위해 등장한 것이 바로 'Swagger'라는 오픈소스 프로젝트이다. 

 

Swagger란?

서버로 요청되는 API 리스트를 HTML 화면으로 문서화하여 테스트 할 수 있는 라이브러리이다. 

이 라이브러리는 서버가 가동되는 @RestController를 읽어 API를 분석하여 HTML 문서를 작성한다. 

 

의존성 추가 

Maven을 기준한다. 

<dependencies>

    [ ... ]
    
    <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>

swagger를 사용하기 위해서는 springfox-swagger2를 의존성에 추가한다.

추가적으로 문서를 예쁘게 보여주고, 테스트 기능을 위해서 springfox-swagger-ui 의존성도 추가하여 사용한다.

 

설정 

com.springboot.api 라고 패키지가 구성되어 있으면 하단에 config라는 패키지를 생성 후 그 안에 SwaggerConfiguration 클래스를 생성한다.

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.springboot.api"))
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("API 문서 제목")
            .description("API 문서 설명")
            .version("1.0.0")
            .build();
    }
}

• @EnableSwagger2
  • Swagger2 버전을 활성화하겠다는 어노테이션이다.
• Docket
  • Swagger 설정의 핵심이 되는 Bean 이다. Swagger에서 API문서의 구성과 메타데이터를 설정하는 데 사용된다. 
  • API 자체에 대한 스펙은 컨트롤러에서 작성한다. 
  • 설정정보
    • apiInfo()
      • 제목, 설명 등 문서에 대한 정보들을 보여주기 위해 호출한다.
    • select()
      • ApiSelectorBuilder를 생성한다.
    • apis()
      • api 스펙이 작성되어 있는 패키지를 지정한다.
      • 즉, 컨트롤러가 존재하는 패키지를 basepackge로 지정하여, 해당 메서드에 설정된 패키지의 하위 패키지 및 클래스를 모두 스캔하여 문서를 생성한다. 
    • path()
      • apis()로 선택되어진 API중 특정 path 조건에 맞는 API들을 다시 필터링해서 문서화한다.

이것은 기본적인 설정이며, 실제 프로젝트에서는 더 많은 세부 설정이 필요할 수 있다. 'springfox' 공식 문서와 여러 가이드를 참고하면 더 다양한 설정 방법을 알 수 있다.

 

추가적으로 Spring Boot 2.6 버전 이후를 사용한다면 application.properties에 아래 내용을 추가하도록 하자. 

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

 

실행 

설정이 끝난 상태에서 애플리케이션을 실행한 후 http://localhost:8080/swagger-ui.html로 접속하면 아래와 같이 Swagger 페이지가 출력된다.

Swagger 페이지

 

Swagger를 더 잘 활용하기 위해선 @RequestParam을 활용한 GET 메서드에 대해 명세의 세부 내용을 설정해 보자.

@ApiOperation(value = "GET 메서드 예제", notes = "@RequestParam을 이용한 GET Method")
@ApiResponses({
        @ApiResponse(code = 200, message = "OK !!"),
        @ApiResponse(code = 500, message = "Internal Server Error !!"),
        @ApiResponse(code = 404, message = "Not Found !!")
})
@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;
}

1번 줄과 4~6번 줄에 추가한 어노테이션은 Swagger가 사용하는 대표 어노테이션이다. 

• @ApiOperation : 대상 API의 대한 설명을 작성하기 위한 어노테이션이다. 
• @ApiParam : 매개변수에 대한 설명 및 설정을 위한 어노테이션이다. 메서드의 매개변수뿐 아니라 DTO 객체를 매개변수로 사용할 경우 DTO 클래스 내의 매개변수에도 정의할 수 있다. 
• @ApiResponse : HTTP 상태 코드를 사용하여 오류를 반환하는 것이 일반적이다, @ApiOperation 어노테이션을 사용하여 오퍼레이션의 가능한 구체적인 응답을 설명할 수 있다.

위와 같이 설정 후 Swagger 페이지를 다시 확인해 보자.

Swagger 페이지에서 확인한 API 명세

@ApiOperation에 작성한 내용은 상단에 표기되고 @ApiParam에 정의한 내용은 아래 'Parameters'와 'Description'에 추가된 것을 확인할 수 있다. 

 

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

Swagger를 통한 통신테스트

각 항목을 기입하고 [Execute] 버튼을 클릭하면 자동으로 완성된 요청 URL를 확인할 수 있고, 그에 따른 결괏값도 받아 볼 수 있다. 

Swagger 통신 테스트 결과