Section 3 - Unit 7 : [Spring MVC] API 문서화 Review

Review 에서는 학습한 내용을 다시금 기록합니다.
Unit Review는 학습한 내용 중 기존에 알고 있었지만 정확하게 이해하지 못하던 정보와 새롭게 알게된 정보를 기록합니다. 추가적인 설명을 요하는 부분은 댓글로 남겨주세요.
Section Review는 전반적인 Section을 되돌아보고 학습했던 시간과 과정, 내용을 총괄하여 기록합니다.

API 문서화

* API 문서화가 필요한 이유

• 클라이언트가 애플리케이션을 사용하기 위해선 애플리케이션의 사용 방법을 알아야 한다. 따라서 애플리케이션에 대한 정보를 담아놓은 API 문서를 작성할 필요가 있다.
  • 예를 들어, Request를 위해선 어떤 정보가 필요한지, 그에 따른 Response에는 어떤 정보가 담겨오는지를 클라이언트 측에 제공해야 한다.

- API 문서 생성의 자동화가 필요한 이유

• 일단 API 문서를 수기로 작성한다는 행위 자체가 너무 비효율적이다. 우리는 개발자다.
• 또한 API 문서를 수기로 작성한다면 필요한 정보의 누락이 발생하는 등의 오류가 있을 수 있다.

- Spring Rest Docs VS Swagger

• 기존에는 Swagger 를 사용하여 API 문서 생성의 자동화를 하는 경우가 많았다.
• Swagger를 사용하면 생성된 API 문서 내에서 POSTMAN을 사용하는 것처럼 HTTP 요청을 보내볼 수 있다.
• 그러나 Swagger를 사용하면 애플리케이션 코드에 핵심 로직과 관계 없는 코드가 지나치게 많이 추가된다는 단점이 있다.
  • 이는 작성이 불편하게 만들 뿐만 아니라, 코드의 가독성 또한 해쳐 좋지 않은 코드를 만든다.
• 반면 Spring Rest Docs를 사용하면 테스트 코드에 약간의 코드를 추가하는 것으로 API 문서를 생성할 수 있다.
• 또한 Spring Rest Docs는 테스트 케이스에서 전송하는 API 문서 정보와 실제 API 계층에서 구현된 정보가 일치하지 않으면 테스트 케이스가 실패하며 API 문서를 생성하지 않는다. 즉, API 문서의 스펙 정보를 누락하는 것을 방지할 수 있다.