API 문서 자동화 1: Spring Rest Docs vs Swagger 장단점 비교

API 문서화

개발자에게는 API를 만드는것 뿐 아니라 이에 대한 문서화 또한 필요하다.

수동으로 Notion이나 스프레드 시트에 정리할 수도 있겠지만 이는 일일이 최신화를 해줘야해서 너무 불편하다.

이런 불편함을 해소하기 위해 API 문서화를 자동으로 해주는 툴이 나왔고, 유명한건 아래 두가지 정도가 있다.

• Spring Rest Docs
• Swagger

한번 이 두가지를 비교해보자.

---

Spring Rest Docs  vs  Swagger

Spring Rest Docs

Spring Rest Docs는 컨트롤러 테스트를 통해 Integration 테스트를 진행하면서 최신화하는 형식이다.

테스트 코드를 통한 방식이기 때문에 Production 코드에 영향을 미치지 않아서 깔끔하게 분리가 가능하다.

또한 테스트를 강제하기 때문에 유지보수에 도움을 준다.

하지만 Swagger처럼 API Test 기능을 지원하지 않고 가시성이 조금 부족하다는 단점이 있다.

아래는 Rest Docs의 예시 이미지이다.

Swagger

Swagger는 컨트롤러나 DTO 등에 애노테이션을 다는걸로 API 문서를 만들어준다.

이전 글에서 Swagger를 써서 API 문서화를 해보았다.

Swagger는 API Test 기능을 지원하고 문서의 가시성이 좋다.

아래는 Swagger의 예시 이미지이다.

 

하지만 Swagger 문서화를 위한 코드가 Production 코드에 너무 깊게 침투한다.

그래서 아래처럼 컨트롤러 코드가 너무 지저분해진다.

---

Spring Rest Docs + Swagger 병용

Swagger를 쓰면서 늘 불편했던 컨트롤러 코드가 지저분해지는 단점을 커버할 수 있단 말에 굉장히 설렜다.

이 방법에 대한 간단한 설명은 아래와 같다.

OpenApi Specification(OAS) 기반 API 문서화

Swagger 팀이 SmartBear Software에 합류하면서 Swagger Spec.이 OpenApi Spec.으로 명칭이 바뀌었고,

오늘날에는 RESTful API 스펙에 대한 사실상의 표준으로서 활용되고 있다고 한다.

Swagger-ui는 이 OAS를 해석하여 API 스펙을 시각화해준다.

또한 Postman, Paw 같은 API Client들도 OAS를 지원하고 있어 OAS를 사용하면 활용도가 높을것으로 예상된다.

OAS를 생성하는 restdocs-api-spec 오픈소스 

그렇다면 Spring REST Docs와 Swagger의 장점을 어떻게 합칠 수 있을까? 

독일 기업 epages에서 Spring REST Docs를 연동하여 OAS 파일을 만들어주는 오픈소스(restdocs-api-spec)를 제공하고 있다.

위에서 Swagger-ui는 OAS를 해석해서 API 스펙을 시각화 해준다고 했다.

따라서 이 오픈소스를 이용해서 OAS 파일을 생성하고 Swagger-ui로 띄우면 된다!

 

 

최근에 한 팀 프로젝트에서는 Swagger를 사용하였는데, Production 코드에 침투하는게 마음에 들지는 않았지만 Swagger의 장점 때문에 유지했었다. (사실 팀원이 테스트 코드를 잘 작성하지 않아서 RestDocs 를 쓰기는 힘들기도 했다.)

하지만 이처럼 Spring Rest Docs와 Swagger를 혼용하여 장점만 취하는 방법을 접하였고 다음 글에서 시도해보려 한다.