Spring Swagger Springfox2 적용

what is swagger?

• Swagger | The World's Most Popular Framework for APIs. http://swagger.io/

guide

• https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X

Quick Annotation Overview

NameDescription| @Api | Marks a class as a Swagger resource. |

@ApiImplicitParam	Represents a single parameter in an API Operation.
@ApiImplicitParams	A wrapper to allow a list of multiple ApiImplicitParam objects.
@ApiModel	Provides additional information about Swagger models.
@ApiModelProperty	Adds and manipulates data of a model property.
@ApiOperation	Describes an operation or typically a HTTP method against a specific path.
@ApiParam	Adds additional meta-data for operation parameters.
@ApiResponse	Describes a possible response of an operation.
@ApiResponses	A wrapper to allow a list of multiple ApiResponse objects.
@Authorization	Declares an authorization scheme to be used on a resource or an operation.
@AuthorizationScope	Describes an OAuth2 authorization scope.
@ResponseHeader	Represents a header that can be provided as part of the response.

적용 방법

SpringFox

• http://springfox.github.io/springfox/
• https://github.com/springfox/springfox
• http://springfox.github.io/springfox/docs/snapshot/
• 최신 버전 : http://mvnrepository.com/artifact/io.springfox/springfox-swagger2
• spring framework 기반에서 더 편리하게 이용 할수 있는 module lib
• @controller 만 정의 되어 있으면. 자동으로 문서 생성
• swagger 2 기반으로 구성 되어 있음.

적용단계

1. maven 설정 추가 : swagger core, swagger ui

   • 
     

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

     
     

2. application context 설정 변경
   • refer : http://springfox.github.io/springfox/docs/snapshot/#docket-spring-java-configuration
   • 해당 swagger 설정을 기존 설정 방식에 import 해줘야 함.
   • 공식 문서에서는 javaconfig 형태를 가이드
   • sample
     • https://gist.github.com/sojw/d8c55001b28d838a096c3256d4b1a7ac#file-swaggerconfiguration-java
       

       
       

       @Configuration @EnableSwagger2 public class SwaggerConfiguration { @Bean public Docket documentation() { return new Docket(DocumentationType.SWAGGER_2).select().apis( RequestHandlerSelectors.basePackage("com.naver")).paths(PathSelectors.any()).build().pathMapping( "/").apiInfo(apiInfo()); } @Bean UiConfiguration uiConfig() { return new UiConfiguration("validatorUrl"); } private ApiInfo apiInfo() { return new ApiInfo("Naver API", "Naver API 명세서", "1.0", "My Apps API terms of service", "naver.blog@navercorp.com", "", ""); } }

       
       

3. mvc 설정 확인
   • swager ui 용 resource 추가
   • 꼭 확인 할 것
     • interceptor 에서 swagger ui 관련 URL 제외
     • web.xml 에서 servlet filter 의 url 패턴 확인
       • ex) /* <- 으로 되어 있는 것을 추천

   • sample : https://gist.github.com/sojw/d8c55001b28d838a096c3256d4b1a7ac#file-springmvcconfiguration-java

     @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(naverLoginInterceptor()).excludePathPatterns("/static/**", "swagger-ui.html", "/webjars/**", "/v2/api-docs", "/configuration/security", "/configuration/ui", "/swagger-resources"); } @Override public void addResourceHandlers(final ResourceHandlerRegistry registry) { registry.addResourceHandler("/static/**").addResourceLocations("/static/"); registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/"); }

     
     

• api doc 접근 : http://도메인/swagger-ui.html

Swagger Core

• https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-2.X-Project-Setup-1.5#configure-and-initialize-swagger
• https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X
• https://github.com/swagger-api/swagger-ui
• http://blog.woniper.net/281
• swagger core lib 기반으로만 적용 할 경우(모든 웹프레임웍에 적용 가능)
• swagger annotaion 을 필수적으로 추가 해야 한다
• jackson lib 는 최신 버전을 유지 해야 한다.
• swagger ui 는 별도 배포본을 설치해야(copy) 한다.

• maven 설정 변경 - swagger core, jackson-core

  <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-core</artifactId> <version>2.7.1</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.7.1</version> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-jersey2-jaxrs</artifactId> <version>1.5.0</version> </dependency>

  
  

• web.xml 설정 변경

  <servlet> <servlet-name>jersey</servlet-name> <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class> <init-param> <param-name>jersey.config.server.provider.packages</param-name> <param-value> io.swagger.jaxrs.listing, com.naver.cafe.mycafe.api <- api scan 할 package 지정 </param-value> </init-param> <load-on-startup>1</load-on-startup> </servlet> <servlet> <servlet-name>Jersey2Config</servlet-name> <servlet-class>io.swagger.jersey.config.JerseyJaxrsConfig</servlet-class> <init-param> <param-name>api.version</param-name> <param-value>1.0.0</param-value> </init-param> <init-param> <param-name>swagger.api.basepath</param-name> <param-value>http://local.cafe.naver.com/swagger/api</param-value> <- 접근 url 정의 </init-param> <load-on-startup>2</load-on-startup> </servlet> <servlet-mapping> <servlet-name>jersey</servlet-name> <url-pattern>/swagger/api/*</url-pattern> <- 접근 url 에 대한 servlet url mapping 설정 </servlet-mapping>