Spring REST API 문서

swagger

Production 환경에서는 REST API를 많이 사용합니다. 그렇다 보니 Api를 문서화해서 호출하는 쪽에 알려줘야 하는 경우가 많습니다. 프로젝트 초창기에는 word 문서로 형식 없이 작성해서 사용했습니다. 그러다 보니 문서 관리도 어렵고, 형식도 제각각이었습니다. 그래서 도입한 것이 RAML입니다. RAML은 REST Api의 documentation을 위해 만든 Language입니다. RAML 파일을 작성한 후 raml2html 같은 tool로 html을 생성해서 사용했습니다. 그렇지만 RAML은 따로 문법을 배워야 하는 어려움이 있었고 RAML 수정 시에 html을 매번 재생성해야 하는 번거로움이 있었습니다.

Spring 진영에는 이러한 번거로움 없이 사용할 수 있는 springfox-swagger2가 있습니다. RAML과 같이 따로 Language를 배우지 않아도 쉽게 사용할 수 있고 html도 수동으로 재생성할 필요 없이 서버 구동 시 자동으로 생성됩니다. 그러면 예제를 통해 springfox-swagger2를 사용하는 방법을 알아보도록 하겠습니다.

1. dependency 추가

build.gradle에 아래 2개 모듈을 추가해 줍니다.      

compile 'io.springfox:springfox-swagger2:2.8.0' 
compile 'io.springfox:springfox-swagger-ui:2.8.0' 

2. Java Config 생성

Docket Bean을 지정하면 기본적인 apidoc을 만들 수 있습니다.      

@Configuration 
@EnableSwagger2 
public class SwaggerConfig {
    
    @Bean
     public Docket docket() {
       return new Docket(DocumentationType.SWAGGER_2).
             select().
             apis(RequestHandlerSelectors.basePackage("com.example.demo")).   
             paths(PathSelectors.any()).      
             build();     
   } 
} 

설정에 대한 자세한 설명은 http://springfox.github.io/springfox/docs/current/#configuration-explained에서 확인할 수 있습니다.

3. Annotation 작성

우선 @Controller 클래스에 @Api를 작성합니다.      

@Api(description = "매장", tags = "Shop") 
@RestController 
public class ShopController { ... } 

tags를 통해 @Api를 그룹핑할 수 있습니다.

다음은 @RequestMapping에 @ApiOperation를 작성합니다.      

@ApiOperation("매장 조회") 
@RequestMapping(value = "/v1/shops/{shopId}", method = RequestMethod.GET) public ShopResponse getShop(@Pathvariable Long shopId){ ... } 

ApiOperation는 단일 오퍼레이션을 가리킵니다.

다음은 위 예제의 ShopResponse와 같은 Http 응답 객체에 Annotation을 작성합니다.      

public class ShopResponse {
     @ApiModelProperty(value = "매장 Id", allowEmptyValue = false)
     private long id;
     @ApiModelProperty(value = "매장 이름", allowEmptyValue = true)
     private String name; 
} 

@ApiModelProperty는 객체의 필드 내용을 적습니다. RequestBody의 객체도 동일하게 작성할 수 있습니다.

4. 문서 확인하기

위 순서대로 작업을 한 후 웹 애플리케이션을 실행해서 http://localhost:8080/swagger-ui.html로 접속하면 아래와 같이 HTML로 작성된 REST API 가이드 페이지를 확인할 수 있습니다.

@API 리스트 중에서 1개를 누르면 아래와 같이 @ApiOperation 들을 확인할 수 있습니다.

그리고 다시 상세를 클릭하면 Operation의 입력과 응답에 대한 내용을 알 수 있습니다.

정리

springfox-swagger2는 정말 좋은 도구입니다. 설정도 간단하고 명세도 Annotation으로 쉽게 작성할 수 있습니다. springboot를 쓰고 계시면서 api documentation을 어떻게 해야 할지 고민이라면 springfox-swagger2를 사용해 보길 바랍니다.

p.s. springfox-swagger2와 같은 annotation을 작성하는 것이 불편하거나 기능이 부족하다고 생각하는 분은 spring-restdocs 을 살펴보세요. 테스트 케이스에 API 명세를 기록하는 멋진 방법도 있습니다.