Spring Boot - Swagger

이번 글은 Spring에서 API 를 문서화할 수 있는 라이브러리 Swagger에 대한 소개입니다.

Why..?

개발을 하고 서버 사이드와 클라이언트 사이드 간의 소통이나 Open API, 협업, 인수인계 등등.. 여러가지 이유로 문서화를 하며, 이는 거의 필수적이라고 할 수 있습니다.

Spring 에서는 RestDocs 와 Swagger 라는 라이브러리를 통해 문서화를 할 수 있습니다. 오늘은 그 중 Swagger 를 이용한 방법을 소개 해보려고 합니다.

How..?

1. Gradle 설정

2. Config 설정

3. Controller 설정

4. Result

---

1. Gradle 설정

- jpa 를 이용하여 간단한 CRUD를 만들어서 문서화를 진행 해보도록 하겠습니다.

dependencies {
	compile('org.springframework.boot:spring-boot-starter-data-jpa')
	compile('org.springframework.boot:spring-boot-starter-web')
	
	compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.5.0'
	compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.5.0'
	
	runtime('com.h2database:h2')
	
	compileOnly('org.projectlombok:lombok')
	testCompile('org.springframework.boot:spring-boot-starter-test')
}

2. Config 설정

- 설정 클래스를 만들고 @EnableSwagger2 선언해줍니다.

- Swagger 에 대한 커스텀을 위해 Docket 을 반환 해줄 Bean 을 만들어 줍니다.

1) Contact : 작성자 정보 

2) ApiInfo  : API 정보

3) Docket

 ① useDefaultResponseMessages : 기본 반환 Message 설정

 ② globalResponseMessage : 전반적인 반환 Message 셋팅(responseMessages 를 보시면 됩니다.)

 ③ apis

  - RequestHandlerSelectors.any() : 모든 url

  - RequestHandlerSelectors.none() : 사용 X

  - RequestHandlerSelectors.basePackage(String path) : path 에 해당하는 단위

 ④ paths(Predicate selector) : PathSelectors 를 이용하여 path 에 대한 설정 가능

3. Controller 설정

- Controller 에 @Api 달아주면 또 다른 설정이 가능 해집니다. Controller 에서는 mappring 에 대한 세부 설정을 보도록 하겠습니다.

[기본 Contoller]

- 기본적인 CRUD 기능을 하는 Controller 에 살을 붙여보도록 하겠습니다.

[Swagger 적용 Controller]

@ApiOperation : mappring 에 대한 전반적인 설명과 필요 조건에 대한 설정

@ApiResponses : 반환 코드에 대해서 message 를 커스텀하게 해줍니다.

 

4. Result

- swagger-ui 를 추가함으로써, 아래와 같은 ui가 만들어집니다. (Base URI : http://localhost:8080/swagger-ui.html)

- 추가로, 커스텀한 mapping 메소드에 대해서 좀 더 상세한 정보를 볼 수 있습니다.

★★ 2016/12-21 추가 ★★

- Model에 대해 Custom 하고자 한다면, @ApiImplictParam, @ApiImplictParams, @ApiModel, @ApiModelProperty를 이용합니다.

@ApiImplictParam, @ApiImplictParams을 Mapping Method 위에 어노테이션을 추가하거나, 반환될 Class에 대한 설정은 @ApiModel, 반환될 Class의 Property들에 대한 설정은 @ApiModelProperty로 가능합니다.

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