05. REST API 명세를 문서화 하는 방법 - Swagger

API 명세서

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

API 개발과정에서 계속 변경되므로 작성한 명세 문서도 주기적인 업데이트가 필요하며
명세 작업은 오랜 시간이 걸릴 수 있기 때문에 이를 해소할 수 있는 것이 바로 Swagger 입니다.

 

Swaager 사용하기

build.gradle에 의존성을 추가해 줍니다.

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

config 라는 패키지를 만들고 하위에 SwaggerConfiguration 클래스를 만들어 줍니다.
아래와 같이 설정해 줍니다.

package com.springboot.api.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@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("Spring Boot Open API Test with Swagger")
                .description("테스트를 위한 API 명세서 입니다.")
                .version("1.0.0")
                .build();
    }
}

http://localhost:8080/swagger-ui/index.html#/ 를 입력하면 아래와 같은 화면이 보입니다.
title : 명세서 타이틀
desc : 상세 설명
version : API 버전 으로 정보를 설정할 수 있습니다.

생성한 컨트롤러에 따라 API 메서드를 확인할 수 있고
Try it out을 통해 테스트 또한 가능합니다.