Swagger With Spring Java

Swagger 란 API로부터 API Document 자동 생성하거나 Server/Client code를 생성 하는 기능을 제공하는 API FRAMEWORK 를 이야기한다. 이런 역활을 해주는 도구들은 많지만, 그 중에서 가장 많이 쓰이고 있는 API FRAMEWORK 가 이다.

아래와 같이이미 작성된 API 코드에서 Swagger Definition(YAML, JSON 등)을 생성하고, 이를 기반으로 Code/API Document를 생성 할 수 있다.

API → Swagger Definition → Server/Client code

API → Swagger Definition → API Document

 

 

https://www.slideshare.net/gakhov/swagger-quick-start-guide

 

Swagger 에서 공식적으로 지원하는 툴 리스트

1. Swagger Core
   → Swagger definition을 생성하는 library
2. Swagger CodeGen
   → Swagger definition을 이용하여 Server/Client code를 생성하는 Command-line tool
3. Swagger UI
   → REST API document web 제공
4. Swagger Editor
   → YAML/JSON 형태의 Swagger definition을 편집하는 editor

 

Swagger 기능

1. 작성된 API 를 기반으로 Swagger Definition Generation
2. 작성된 API 를 기반으로 API Document Web Service → Swagger-UI)
3. Swagger Definition 을 기반으로 Test Code Generation → Swagger CodeGen
4. Swagger Definition 을 기반으로 API Document Web Service → Swagger-UI

 

Swagger 환경 설정

Springfox를 이용한 Swagger 연동 방법은 아래와 같은 순서로 진행 하면 된다.

1. maven dependency에 Springfox 라이브러리 추가
2. Swagger Configuration 파일을 추가
3. Swagger UI 를 resource 에 추가
4. Swagger JSON 생성 확인

 

1. maven dependency에 Springfox 라이브러리 추가

<!--  For Swagger core, 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. SwaggerConfiguration 파일 추가

SwaggerConfiguration 은 어떤 Package 에 추가하든 상관 없지만 가급적이면 Config 관련 Package 에 추가하는걸 권장한다.

 

// Swagger 2.0 version을 사용 annotation
@EnableSwagger2                               
// 설정 파일 annotation
@Configuration                                
// WebMvc 사용 설정 annotation
@EnableWebMvc    
// REST API 를 찾을 Package 지정 annotation
@ComponentScan({ "ga.jjeaby.rest.api" })     
public class SwaggerConfiguration {
  @Bean
  public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.any())
                   .paths(springfox.documentation.builders.PathSelectors.regex("/.*")).build();
   }
}

 

 

3.Swagger UI 를 resource 에 추가

servlet-context 에 Swagger UI 의 resources 에 추가하고 AOP 로 인증 처리를 하는 경우 Swagger UI 의 path 를 인증 AOP 에서 Exclude 하도록 규칙을 추가한다

 

<mvc:resources location="classpath:/META-INF/resources/swagger-ui.html" mapping="swagger-ui.html" /> 
<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**" /> 
<mvc:interceptors>
	<mvc:interceptor>
	   <mvc:mapping path="/**" />
	   
    	   <!-- For Swagger UI, Rest V1 Except Auth -->
	   <mvc:exclude-mapping path="/swagger-ui.html" />
	   <mvc:exclude-mapping path="/swagger-resources" />
	   <mvc:exclude-mapping path="/webjars/** " />
	   <mvc:exclude-mapping path="/v2/api-docs" />
....

 

 

4. Spring 서버 구동시 Swagger JSON 생성 확인

• 서버 구동시 /v2/api-docs 가 Mapping 되는지 Log 를 확인
• 크롬으로 localhost:8080/v2/api-docs 에 접속하면 Json 파일이 열리는지 확인

 

Swagger 적용 확인

1 ~ 4번까지 정상적으로 진행 되었다면 Swgger UI 접속하여 API Document Spec 을 보고 매뉴얼 테스트를 수행 할수 있다

크롬으로 localhost:8080/swagger-ui.htm 에 접속하면 Swagger-UI 에 접속할 수 있다