spring boot에 swagger2 적용

Swagger는 간단한 설정으로 rest api문서 자동화를 해주는 프레임워크다.

 

dependency 적용

 - swagger2 기능을 지원 

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

 - swagger2 ui 지원

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

 - swagger2 ui의 유효성 검증 지원

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-bean-validators</artifactId>
            <version>2.9.2</version>
        </dependency>

java config 설정

@Configuration
    @EnableSwagger2
    @Import({BeanValidatorPluginsConfiguration.class})
    public static class SpringFoxConfig {
        @Bean
        public Docket api() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .select()
                    .apis(RequestHandlerSelectors.any())
                    .paths(PathSelectors.any())
                    .build();
        }
    }

 - spring boot project 는 @EnableSwagger2 annotation을 적용하면 swagger을 활성합니다.

 - @Import에 BeanValidatorPluginsConfiguration.class 를 추가해 swagger에 validation annotation이 붙은 필드의 유효성 값을 확인 할 수 있습니다.

 - Docket 생성자를 통해 DocumentationType(swagger 버전)을 parameter로 넘겨 생성해야한다.

 - apis() method를 통해 요청 핸들러가 포함되면 추가 한다.

  ex) RequestHandlerSelectors.any() : 모든 request가 충족

  ex) RequestHandlerSelectors.basePackage(String) : parameter로 넘겨진 basePackage 경로에 포함된 request만

  - ...이 외에도 몇가지 method가 더 존재함.

 - paths() method를 통해 들어오는 requestMapping(URL)이 조건에 맞으면 추가한다.

  ex) PathSelectors.any() : 모든 path가 충족

  ex) PathSelectors.regex(String) : 정규식을 만족하는 url만

 - bulid() method 를 통해 작성한 apis,paths를 가진 Docket 인스턴스를 리턴한다.

 

server.contextPath: /

Swagger UI endpoint : {server.contextPath}/v2/api-docs

Swagger docs endpoint : {server.contextPath}/swagger-ui.html