API Documentation

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

API 사용을 위한 어떤 정보가 담겨 있는 문서를 API 문서 또는 API 스펙(사양, Specification)이라 한다

API 문서는 개발자가 요청 URL,URI 등의 API 정보를 직접 수기로 작성할 수도 있고, 애플리케이션 빌드를 통해 API 문서를 자동 생성할 수 도 있다.

왜 API 문서 생성의 자동화가 필요할까?

API 문서를 수기로 직접 작성해야 하는것은 너무나 비효율적인 문제이다

또한 한번 작성된 API 문서에 기능이 추가되거나 수정되면 API 문서 역시 함께 수정되어야 하는데, 아무래도 사람이 직접 하는 일이다보니 깜빡하고 API 문서에 추가된 기능을 빠뜨릴수도 있고, 클라이언트에게 제공된 API 정보와 수기로 작성한 API 문서의 정보가 다를수 있다.

Swagger의 API 문서화 방식

• 애터네이션 기반의 API 문서화 방식
• 애플리케이션 코드에 문서화를 위한 애너테이션들이 포함된다.
• 가독성 및 유지 보수성이 떨어진다.
• API 문서와 API 코드 간의 정보 불일칠 문제가 발생할 수 있다.
• API 툴로써의 기능을 활용할 수 있다.

Spring Rest Docs의 API 문서화 방식

• 테스트 코드 기반의 API 문서화 방식
• 애플리케이션 코드에 문서화를 위한 정보들이 포함되지 않는다.
• 테스트 케이스의 실행이 "passed" 여야만 API 문서가 생성된다 (failed 시 생성 안됌)
• 테스트 케이스를 반드시 작성해야 된다.
• API 툴로써 기능을 제공하지 않는다.