REST API 문서화는 세 가지 관점에서 고려한다.
- API 서버 소스코드
- API 문서 브라우징
- API 테스트 드라이브
그리고 다음과 같은 요구사항을 만족해야 한다.
- 문서의 기본 골격은 소스코드에서 생성하며, 소스코드에서 알 수 있는 내용은 수동으로 입력하지 않는다.
- 소스코드에서 생성한 문서에 쉽게 코멘트나 포맷팅 가능한 설명을 추가할 수 있다.
- 문서는 파싱해서 API 테스트 UI를 자동 생성할 수 있다.
필요한 정보
- Data schema description language for request and response
- primitive types
- list or dictionary
- reference to other type
- request parameter spec
- url parameter
- form field
- header
- cookie