안녕하세요! 오늘은 Spring 진영의 문서화 프레임워크인 Spring Rest Docs와 Swagger를 비교하는 글을 작성해 볼까 합니다. Peloton 프로젝트 진행 중에 문서화와 관련해서 고민했던 부분들을 정리 해보았어요. 함께 공유해보면 좋을 것 같아요.

Spring Rest Docs의 특징

Spring Rest Docs로 작성된 문서

Spring Rest docs는 Test 기반으로 동작합니다. 테스트 코드에 추가함으로써 문서가 작성돼요. 따라서 Production 코드에 영향을 미치지 않는다는게 큰 장점입니다. 테스트 기반이기 때문에 테스트가 수행되지 않으면 문서 또한 작성되지 않아요. 따라서 문제가 있는 경우엔 문서또한 작성되지 않는다는 장점(?)이 있죠.
(물론 테스트가 수행되지 않는 서비스에 대해서도 문서를 보고싶은 사람도 있겠지만요.) 또한 문서 본연의 기능에 충실합니다.

하지만 테스트 기반으로 설계된 서비스가 아니라면, 사용이 불가능합니다. 또한 추가적인 설정들을 적용하기가 쉽지 않다는 단점을 가지고 있어요. 또한 사진에서 보시는 것 처럼 문서가 그렇게 이쁘지 않아요😅

마지막으로 엔드 포인트마다 수많은 코드를 추가해줘야 한다는 단점이 있습니다. 반복성 작업을 해야해서 굉장히 힘들었습니다😭 중복을 제거하려면 좀 더 고민을 해봐야겠어요.

Swagger의 특징

Swagger로 작성된 페이지

Spring Rest Docs와 반대로 Open Api로 작성된 문서는 Swagger UI를 통해 알록달록 굉장히 이쁩니다. 또한 의존성만 추가해도 이런 인터페이스를 한번에 제공하죠. 그리고 실제 API를 테스트하는 기능 또한 제공해요. 만약 Admin Page가 없다면, 이런 기능을 유용하게 사용할 수 있을 것 같아요!

API 테스트 해보기

심지어 작성된 객체의 필드도 보여준다..!

하지만 지금까지의 Swagger는 문서화 도구보단 API 테스터에 가까워요. 원하는 엔드포인트나 필요한 리소스들에 대한 설명은 어떻게 추가해줘야 할까요?

@Operation(summary = "Get a book by its id")
@ApiResponses(value = { 
  @ApiResponse(responseCode = "200", description = "Found the book", 
    content = { @Content(mediaType = "application/json", 
      schema = @Schema(implementation = Book.class)) }),
  @ApiResponse(responseCode = "400", description = "Invalid id supplied", 
    content = @Content), 
  @ApiResponse(responseCode = "404", description = "Book not found", 
    content = @Content) })
@GetMapping("/{id}")
public Book findById(@Parameter(description = "id of book to be searched") 
  @PathVariable long id) {
    return repository.findById(id).orElseThrow(() -> new BookNotFoundException());
}

프로덕션 코드에 직접 어노테이션을 추가하는 방식으로 문서화를 구현할 수 있어요. 결과는 다음과 같죠.

보시다시피 프로덕션 코드에 문서화와 관련된 코드가 추가된다는 점이 OpenApi의 단점이 아닐까 싶어요. 예제 코드만 보더라도 가독성이 굉장이 떨어지고, 실제 컨트롤러는 어디서부터 시작되는지 조차 파악하기 어렵죠. 또한 객체 지향의 관점에서도 컨트롤러에 문서화라는 역할이 추가되는 느낌이에요.

또한 테스트가 정상적으로 동작하지 않아도 문서가 작성된다는 문제점등이 있을 것 같아요.

정리

정리해보자면 각 장단점은 이렇게 될 것 같아요. 본인의 서비스에 맞게 선택하셔서 사용하는게 가장 좋을 것 같습니다!

Spring Rest Docs

장점	단점
테스트 기반으로 수행됨	세부 설정하기 어려움
프로덕션 코드에 영향을 주지 않음	엔드포인트에 따른 코드가 많음
문서에 대한 신뢰성이 높음	추가적인 기능을 제공하지 않음
문서 본연의 기능에 충실함	문서가 예쁘지 않음..😭

Swagger

장점	단점
문서가 예쁘다	프로덕션 코드의 가독성이 떨어짐
API 테스트 기능을 제공	문서의 신뢰도가 떨어짐(테스트 기반이 아님)
객체들에 대한 정보를 제공	라이브러리의 무게가 무거움
의존성 추가만 해도 기본 UI를 제공	많은 어노테이션들을 학습해야함
TDD 서비스가 아니어도 사용가능

출처

우아한 형제들 기술블로그
Baeldung
Swagger