간단한 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

 

SwaggerConfig 추가

package com.gworld.weather.config;

import io.swagger.annotations.SwaggerDefinition;
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;

@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();
    }
}

주소에 http://localhost:8080/swagger-ui/index.html 입력

 

내가 만들지 않은 basic-error-controller를 보여주고 싶지 않고,
프로젝트에 있는 API 목록들만 가지고 오고 싶은 경우 아래와 같이 경로를 지정해준다.

.apis(RequestHandlerSelectors.basePackage("com.gworld.weather"))

Path중에 특정 API들만 보여주고 싶은 경우 ant 패턴을 통해서 설정해줄 수 있다.

예로 들면, 모든 데이터 삭제나 특정 개발을 위해서 잠깐 만든 메소드들의 경우 보여줄 필요가 없거나, 보여주면 안되므로 해당 부분들을 처리하기 위해서 설정해줄 수 있다. 

.paths(PathSelectors.ant("/read/**"))

 

 

그리고 마지막으로 API들을 설명해주기 위해서 Controller 에서 @ApiOperation과 @ApiParam을 설정해 줄 수 있다.

먼저, @ApiOperation의 경우에는 기본적으로 method의 이름인 deleteDiary, 설명인 Parameters가 보여지지만

아래와 같이 설정해줄 수 있다.

@PostMapping("/create/diary")
@ApiOperation(value="다이어리 생성 API", notes = "다이어리 생성 API의 설명은...")
void createDiagry(){
    ...
    ...
}

 

그리고 파라미터도 형식을 명확하게 알려주고, 설명을 해주기 위해서는 ApiParam을 활용할 수 있다.

@PostMapping("/create/diary")
@ApiOperation(value="다이어리 생성 API", notes = "다이어리 생성 API의 설명은...")
void createDiagry(
        @RequestParam @DateTimeFormat(iso=DateTimeFormat.ISO.DATE)
        @ApiParam(value="조회할 기간의 마지막날", example = "2020-02-02")
        LocalDate date,
        @RequestBody String text){
    
        diaryService.createDiagry(date, text);
}