[SPRING MVC] API 문서화

📌 API 문서화란?

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

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

수기로 작성하게되면 너무나 비효율적이고, 클라이언트에게 제공된 API 정보와 수기로 작성한 API 문서의 정보가 다를 수도 있기 때문이다.

작업 시간을 단축하고, 애플리케이션의 완성도를 높여준다.

📌 Spring Rest Docs

Spring rest Docs의 API 문서 생성 흐름

1. 테스트 코드 작성

   • 슬라이스 테스트 코드 작성
   • API 스펙 정보 작성

2. test 태스크 실행

   • 작성된 슬라이스 테스트 코드를 실행한다.
   • 테스트 실행 결과가 passed면 다음 작업을 진행하고, failed면 문제를 해결하기 위해 테스트 케이스를 수정하고, 다시 진행한다.

3. API 문서 스니펫(.adoc 파일) 생성

   • 테스트 케이스의 테스트 실행 결과가 passed이면 테스트 코드에 포함된 API 스펙 정보 코드를 기반으로 API 문서 스니펫이 .adoc확장자를 가진 파일로 생성된다.

4. API 문서 생성

5. API 문서를 HTML로 변환

   • HTML 파일 자체를 공유할 수도 있고, URL을 통해 해당 HTML에 접속해서 확인 가능