API 문서화란?
- 클라이언트가 REST API 백엔드 애플리케이션에 요청을 전송하기 위해서 알아야 되는 요청 정보(URL,URI,request body,query parameter 등)를 문서로 잘 정리하는 것을 의미한다.
- REST API 기반의 백엔드 애플리케이션을 클라이언트 쪽에서 사용하려면 API 사용을 위한 어떤 정보가 필요로 하기 때문에 문서화 작업이 필요하다.
- API 문서는 개발자가 요청 URL(또는 URI) 등의 API 정보를 직접 수기로 작성할 수도 있고, 애플리케이션 빌드를 통해 API 문서를 자동 생성할 수 있다.
API 사용을 위한 어떤 정보가 담겨 있는 문서를 API 문서 또는 API 스펙이라고 한다.
API 문서 생성의 자동화가 필요한 이유
- API 문서를 수기로 직접 작성해야 하는 것은 너무나 비효율적이다.
- API 문서에 추가된 기능을 빠드릴 수 있다.
- 클라이언트에게 제공된 API 정보와 수기로 작성한 API 문서의 정보가 다를 수 있다.
Spring Rest Docs vs Swagger
보통 Spring 에서 문서화를 할 때, Swagger과 RestDocs를 사용하게 된다.
swagger의 특징으로는
- 로직에 애너테이션을 통해 명세를 작성하게 되는데 지속적으로 사용하게 된다면 명세를 위한 코드들이 많이 붙게되어 전체적으로 가독성이 떨어진다.
- 테스트 기반이 아니기에 문서가 100% 정확하다고 확신할 수 없다.
- 모든 오류에 대한 여러 가지 응답을 문서화할 수 없다.
반면 REST Docs를 사용하면 다음과 같은 이점이 있다.
- 테스트 기반으로 문서가 작성되어 테스트 코드가 일치하지 않으면 테스트 빌드가 실패하게 되기 때문에 문서를 신뢰할 수 있다.
- 테스트 코드에서 명세를 작성하기 때문에 비즈니스 로직의 가독성에 영향을 미치지 않는다.
REST Docs란?
- 테스트 코드 기반으로 Restful API 문서를 돕는 도구이다.
- Asciidoctor를 이용해서 HTML 등등 다양한 포맷으로 문서를 자동으로 출력할 수 있다.
- RestDocs의 가장 큰 장점은 테스트 코드 기반으로 문서를 작성한다는 점이다.
- API Spec과 문서화를 위한 테스트 코드가 일치하지 않으면 테스트 빌드를 실패하게 되어 테스트 코드로 검증된 문서를 보장할 수 있다.
Spring Rest Docs의 API 문서 생성 흐름
- 테스트 코드 작성
- 슬라이스 테스트 코드 작성
- Spring Rest Controller는 슬라이스 테스트와 밀접한 관련이 있다. 따라서 Controller에 대한 슬라이스 테스트를 생성한다.
- API 스펙 정보 코드 작성
- 슬라이스 테스트 코드 다음에 Controller에 정의되어 있는 API 스펙 정보(Request Body,Response Body,Query Parameter 등)를 코드로 작성한다.- test 태스크 실행
- 작성된 슬라이스 테스트 코드를 실행
- 하나의 테스트클래스를 실행시켜도 되지만 일반적으로 Gradle의 빌드 태스크 중 하나인 test task를 실행시켜서 API 문서 스니펫을 일괄 생성한다
- 테스트 실행결과가 "passed"이면 다음 작업을 진행하고, "failed"이면 문제를 해결하기 위해 테스트케이스를 수정한 후, 다시 테스트를 진행해야 한다.- API 문서 스니펫(.adoc 파일) 생성
- 테스트 케이스의 테스트 실행 결과가 "passed"이면 테스트 코드에 포함된 API 스펙 정보 코드를 기반으로 API 문서 스니펫이 .adoc 확장자를 가진 파일로 생성된다.
- 스니펫 : 스니펫은 일반적으로 코드의 일부 조각을 의미하는 경우가 많은데 여기서는 문서의 일부 조각을 의미한다.
- 스니펫은 테스트 케이스 하나당 하나의 스니펫이 생성되며, 여러 개의 스니펫을 모아서 하나의 API 문서를 생성할 수 있다.- API 문서 생성
- 생성된 API 문서 스니펫을 모아서 하나의 API 문서로 생성한다.- API 문서를 HTML로 변환
- 생성된 API 문서를 HTML 파일로 변환한다.
- HTML로 변환된 API 문서는 HTML 파일 자체를 공유할 수 있고, URL을 통해 해당 HTML에 접속해서 확인할 수 있다.Reference
" To be BE "