Swagger 적용

Swagger를 통해 지금까지 만들었던 API들을 문서화해보겠습니다.

의존성 추가

//swagger
    implementation 'io.springfox:springfox-swagger2:2.9.2'
    implementation 'io.springfox:springfox-swagger-ui:2.9.2'

application.properties에 오류 해결 설정

spring.mvc.pathmatch.matching-strategy=ant-path-matcher

Swagger 빈 설정

Swagger 작동에 필요한 내용들을 설정해주기 위한 Configuration 파일입니다.

예전에 @Configuration에 대해서 다룰 때, @Configuration 내부의 @Bean 메서드를 통해 빈을 생성하는 작업에 대한 힌트를 작성한다고 말씀드렸습니다. 지금 하는 작업도 스프링컨테이너에 실릴 Swagger 와 관련된 빈에 대한 설정을 해주는 것입니다.

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .consumes(getConsumeContentTypes())
                .produces(getProduceContentTypes())
                .apiInfo(getApiInfo())
                .select()
                //Swagger의 스캔 대상이 될 패키지를 입력합니다.
                .apis(RequestHandlerSelectors.basePackage("org.cau.hellspringboot"))
                //해당 패키지 중 스캔 대상이 될 path를 한정할 때 사용합니다.
                .paths(PathSelectors.ant("/api/**"))
                .build();
    }

    private Set<String> getConsumeContentTypes() {
        Set<String> consumes = new HashSet<>();
        consumes.add("application/json;charset=UTF-8");
        consumes.add("application/x-www-form-urlencoded");
        return consumes;
    }

    private Set<String> getProduceContentTypes() {
        Set<String> produces = new HashSet<>();
        produces.add("application/json;charset=UTF-8");
        return produces;
    }

    private ApiInfo getApiInfo() {
        return new ApiInfoBuilder()
                .title("HellSpringBoot API Sheet")
                .description("It is Hellspringboot API")
                .contact(new Contact("Pete", "site.com", "sbslc2000@gmail.com"))
                .version("1.0")
                .build();
    }
}

결과

localhost:8080/swagger-ui.html/ 에 접속하면 다음과 같이 Swagger가 만든 페이지를 확인할 수 있습니다. 빈을 설정할 때 입력했던 정보들 역시 확인할 수 있습니다.

각각의 api 엔드포인트를 눌러보면 다음과 같이 어떤 데이터를 어떤 형식으로 요구하는지, 결과의 형식은 무엇인지 등의 정보를 얻을 수 있습니다.

Swagger Annotation들을 활용해서 내용 보강하기

위의 내용들은 Swagger가 자동으로 만들어준다는 점에서 매우 편리하지만, 아주 기초적인 정보만 담고 있습니다. API 문서를 만들 때에는 여러 부가적인 정보를 제공해야할 필요가 있습니다. 이를 위해서 Swagger Annotation들을 사용하여 내용을 보강해보겠습니다.

@Api