Swagger2 설정 및 사용

설정 

의존성 추가 

build.gradle에 아래 의존성들을 추가

// support swagger doc
compile ('io.springfox:springfox-swagger2:2.9.2')

 

 

Application 설정 추가

application.yml 파일에 설정 추가

springdoc:
  swagger-ui:
    path: /test/api-docs.html # swagger ui html 파일 경로 설정, 컨트롤러에서 해당 경로를 호출하면 자동 생성된 swagger 페이지가 보인다.
  paths-to-match: /api/** # 매칭 기본 URL 설정

 

 

Bean 등록 

기본설정 - 설정된 /api/** 이하의 모든 API의 명세를 생성. 

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any()) // 현재 RequestMapping으로 할당된 모든 URL 리스트를 추출
                .paths(PathSelectors.ant("/api/**")) // 그중 /api/** 인 URL들만 필터링
                .build();
    }
}

 

 

Swagger 설정 예시

Swagger의 기본설정으로는 API의 표출등 제어가 힘들기 때문에 다음과 같이 다양한 옵션과 제약으로 설정. 

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(this.info())
            .enable(true)
            .select()
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            .apis(RequestHandlerSelectors.basePackage(baseApiPkg))
            // Ignore. display internal api's
            .paths(Predicates.not(PathSelectors.ant("/api/mail/**")))
            .paths(Predicates.not(PathSelectors.ant("/api/**/internal/**")))
            .paths(Predicates.not(PathSelectors.ant("/api/**/externall/**")))

            .build()
            .useDefaultResponseMessages(false)
            .genericModelSubstitutes
            (
                    Optional.class,
                    DeferredResult.class,
                    ResponseEntity.class,
                    ResponseMessage.class,
                    Single.class,
                    Observable.class,
                    Maybe.class
            )
            .ignoredParameterTypes(
                    WebRequest.class,
                    HttpServletRequest.class,
                    HttpServletResponse.class,
                    HttpSession.class,
                    Principal.class,
                    Locale.class
            )
    ;
}

 

 

API에 Swagger Annotation 추가 

• API에 대한 상세 제어가 필요할 경우 사용 

• 다양한 타입이 존재하므로 Swagger 문서 확인 필요

@ApiOperation(
        value = "조회",
        notes = "관리자 전용 함수 입니다\n",
        response = ResponseMessage.class
)
@ApiImplicitParams({
        @ApiImplicitParam(name = "Authorization", required = true,  dataType = "string", paramType = "header", value = "authorization header",   defaultValue = "ah "),
        @ApiImplicitParam(name = "status",        required = true,  dataType = "string", paramType = "query",  value = "코드)",   				defaultValue = "0"),
        @ApiImplicitParam(name = "companyName",   required = false, dataType = "string", paramType = "query",  value = "상호",            		defaultValue = "test"),
        @ApiImplicitParam(name = "corporateNum",  required = false, dataType = "string", paramType = "query",  value = "사업자 번호",				defaultValue = "1XX-8X-4XXXX"),
        @ApiImplicitParam(name = "all",           required = false, dataType = "string", paramType = "query",  value = "출력여부",					defaultValue = "n"),
        @ApiImplicitParam(name = "page",          required = true,  dataType = "string", paramType = "query",  value = "페이지번호",                 defaultValue = "1"),
        @ApiImplicitParam(name = "size",          required = true,  dataType = "string", paramType = "query",  value = "출력수",                    defaultValue = "10"),
        @ApiImplicitParam(name = "sort",          required = false, dataType = "string", paramType = "query",  value = "정렬(number.desc)",         defaultValue = ""),
})
@Splunk(actionType = ActionType.PRIVACY_VIEW_LIST, menu = "파트너관리")
@GetMapping(value = {""})
public DeferredResult<ResponseMessage<List<Partner>>> searchPartnerByPage(WebRequest request,
                                                                          @RequestParam(name = "all",  required = false, defaultValue =  "n")  String isInput,
                                                                          @RequestParam(name = "page", required = false, defaultValue =  "1")  int page,
                                                                          @RequestParam(name = "size", required = false, defaultValue = "10")  int size,
                                                                          @RequestParam(name = "sort", required = false)                       String sort)
{
    DeferredResult<ResponseMessage<List<Partner>>> deferred = new DeferredResult<>();
    partnerService.rxSearchPartnerByPage("Y".equalsIgnoreCase(isInput), page, size, request)
            .subscribeOn(Schedulers.io())
            .onErrorResumeNext(t -> Single.error(new DefaultException(t.getMessage())))
            .subscribe( s -> success(deferred, request, s),
                        e -> failure(deferred, HttpStatus.INTERNAL_SERVER_ERROR, e));
    return deferred;
}