RESTFUL 서비스를 개발하는데 도움이 되는 도구를 둘 소개한다.
apiary
우선 베타 서비스 중인 apiary가 있다. 홈페이지의 제품 설명은 그럴 듯 하지만 직접 써보기 전에는 감이 안 온다. 간단히 설명해 Restful API를 설계하고 프로토타이핑하는 서비스이다.
Blueprint라는 서비스 전용 문법에 따라 간략하게 문서와 API를 적으면 프로그래밍 언어별 예제와 Mockup 사이트를 생성한다. 일종의 프로토타이핑 서비스라 생각하면 된다. 상당히 직관적이고 예제가 충분해 사용법을 금방 익힌다. Markdown을 지원하니 문서 쓰기도 편하다. 그리고 친구를 불러 협업할 수도 있다. 기업용 서비스도 제공하던데 프로젝트 참여 인원이 많지 않아 당장은 쓸 일이 없을 듯 싶다.
아쉬운 점
- Java용 예제 코드를 제공하지 않는다.
Swagger
Swagger는 Restful API 문서화 시스템이다. 정확하게 말하면 문서화 규약인데 언어나 프레임워크 별로 구현체가 존재한다. 물론 구현체가 없을 때도 있다. Spring Framework의 경우 구현체를 둘 정도 발견했다. 그 중에서 Spring MVC and Swagger. Generating documentation for your RESTful web services – PART 2에서 언급한 조합을 사용했다.
전자는 Spring MVC의 코드를 토대로 문서 내용을 자동으로 생성한다.
@ApiOperation(value = "Method to update a book")
@RequestMapping(method = RequestMethod.PUT, value = "/{bookId}")
public @ResponseBody OperationResult update(
@ApiParam(required = true, value = "The id of the book that should be updated", name = "bookId")@PathVariable("bookId") String bookId,
@ApiParam(required = true, name = "book", value = "The book object that needs to be updated")@RequestBody Book book){
return bookDAO.update(bookId, book);
}
후자는 그렇게 생성한 내용을 웹 페이지로 변환해 사용자 인터페이스를 제공한다.
apiary처럼 웹 페이지 상에서 바로 API를 테스트해 볼 수 있다. apiary와 달리 실제 코드를 바로 문서로 뽑아내기 때문에 문서와 실제 API의 버전이 안 맞을 일은 없다.
아쉬운 점
@ApiOperation어노테이션을 이용해 상세 설명을 쓰기 때문에 Markdown을 이용하는 apiary에 비해 불편하고 표현력이 부족하다.
