Swagger - REST API 명세를 문서화 하기

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

 

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

 

Swagger를 사용하기 위해서는 build.gradle 파일에 의존성을 추가해야 한다.

implementation 'io.springfox:springfox-boot-starter:3.0.0'
implementation 'io.springfox:springfox-swagger-ui:3.0.0'

 

그리고 application.properties 파일에 설정을 추가한다.

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

 

Swagger와 관련된 설정 코드를 작성한다.

@Configuration
@SwaggerDefinition
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build().apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("title")
                .description("description")
                .version("1.0")
                .build();
    }
}

 

위의 설정을 마치면 ~/swagger-ui/index.html 주소를 이용하여 페이지에서 확인할 수 있다.