spring boot swagger2 사용하기

1. maven dependency 추가

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>
 
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
</dependency>

2. @Configuration 설정

@Configuration
@EnableSwagger2
public class SwaggerConfig {
 
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.kyu.boot.controller"))
                .paths(PathSelectors.any())
                .build()
                .useDefaultResponseMessages(false)
                .globalResponseMessage(RequestMethod.GET,
                        newArrayList(new ResponseMessageBuilder()
                                        .code(500)
                                        .message("Internal Server Error")
                                        .responseModel(new ModelRef("Error"))
                                        .build(),
                                new ResponseMessageBuilder()
                                        .code(400)
                                        .message("Bad Request")
                                        .build(),
                                new ResponseMessageBuilder()
                                        .code(404)
                                        .message("Not Found")
                                        .build()));
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("test swagger2")
                .description("swagger2 사용해 봅시다.")
                .build();
 
    }
}

apis 메서드에는 swagger를 적용할 패키지 경로를 작성하면 된다.

RequestHandlerSelectors.any() 와 같이 설정 가능하지만 비즈니스에서 사용하는 api 외에 스프링 부트에서 제공하는 api도 함께 출력된다.

paths 메서드에는 어떤 규칙의 uri 패턴을 설정하는 구간이다. (ex : "/api/**")

3. swagger-ui 접속

http://localhost:8080/swagger-ui.html 페이지에 접속하면 swagger 페이지가 보여지게 된다.

4. annotaion 사용 방법

@Slf4j
@RestController
@Api(value = "main", description = "main controller")
public class MainController {
 
    @ApiOperation(value = "메인 페이지")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "area", value = "지역", required = true, dataType = "string", paramType = "path"),
            @ApiImplicitParam(name = "param1", value = "파라미터1", required = true, dataType = "string", paramType = "query"),
            @ApiImplicitParam(name = "param2", value = "파라미터2", required = true, dataType = "int", paramType = "query"),
            @ApiImplicitParam(name = "param3", value = "파라미터3", required = false, dataType = "int", paramType = "query")
    })
    @GetMapping(value = "/main/{area}")
    public ResultMain main(@PathVariable String area
            , @RequestParam String param1
            , @RequestParam int param2
            , @RequestParam(required = false, defaultValue = "0") int param3
            , @RequestHeader("remoteAddr") String remoteAddr) {
 
        ResultMain resultMain = new ResultMain();
        resultMain.setParam1(param1);
        resultMain.setParam2(param2);
        resultMain.setParam3(param3);
        return resultMain;
    }
}
 
@Data
public class ResultMain {
 
    @ApiModelProperty(notes = "파라미터1", required = true)
    private String param1;
    @ApiModelProperty(notes = "파라미터2", required = true)
    private int param2;
    @ApiModelProperty(notes = "파라미터3", required = true)
    private int param3;
}

@Api(value = "main", description = "main controller")

@ApiOperation(value = "메인 페이지")

@ApiImplicitParams

@ApiModelProperty

[참고]

스프링 시큐리티가 적용되어 있다면 swagger에서 사용하는 URL에 대한 예외 처리가 필요하다.

application.yml 설정에 spring.resources.add-mappings=false 로 되어 있다면 true로 변경해야 /swagger-ui.html 페이지 호출이 가능하다.