API 문서는 API를 호출하는 방법과 입력·출력·오류 조건을 설명하는 자료다. HTTP API의 경우 주소와 메서드, 매개변수, 응답 형식을 함께 다룬다. (OpenAPI 명세)
- 성공 응답만 보여주면 실패했을 때의 처리를 알 수 없다. 필수 입력과 인증 방식, 가능한 응답 코드를 함께 제시한다. (매개변수·보안·응답 객체)
- 예시는 실제 스키마와 맞아야 한다. 문서의 예시를 복사했는데 필수 값이 빠져 있으면, 시작하려던 사람이 먼저 문서를 고쳐야 한다. (OpenAPI의 예시 객체)
- OpenAPI는 HTTP API의 구조를 기계가 읽을 수 있게 기술한다. 이 명세를 문서 생성과 클라이언트 코드 생성 등에 활용할 수 있다. (OpenAPI의 목적)