[ Spring ] API 문서화와 Spring Rest Docs는 무엇일까?!

API 문서화란 무엇일까??!!!

 

API문서화는 클라이언트가 REST API 백엔드 애플리케이션에 요청을 전송하기 위해서 알아야 되는 요청정보(URL, request body, query parameter 등)을 문서로 잘 정리해 놓은 것을 뜻합니다.

 

우리는 이러한 문서를 API 문서 또는 API 스펙이라고 합니다.

 

이러한 API문서는 수기로 작성할 수 있지만 애플리케이션 빌드를 통해 자동 생성할 수 있습니다.

 

Spring Rest Docs

 

애플리케이션 빌드는 대표적으로 Swagger와 Spring Rest Docs가 있지만 Swagger는 Spring Rest Docs 에 비해 오래된 기술입니다. 

Swagger는 애너테이션 기반의 애플리케이션 빌드이며 Swagger를 사용할 때 너무 많은 애너테이션을 사용하기 때문에 가독성이 떨어지고 코드가 길어지는 단점이 있습니다.

 

반면에, Spring Rest Docs는 테스터 클래스에서 비교적 짧은 양의 코드로 구현이 가능합니다.

또한 우리가 메인에서 구현한 코드가 테스팅 문서와 일치하지 않는다면 API문서가 생성되지 않습니다. 

따라서, 테스팅이 100퍼센트 성공하였을 때 API 문서가 만들어집니다. 

 

다만, 테스트 케이스를 직접 작성해야하며 이들을 모두 통과해야 API 문서가 만들어진다는 단점이 있습니다.