서비스를 설명하는 문서
API를 호출하는 쪽이 서버 소스 코드를 직접 보거나 통신을 추측하지 않고도 기능을 이해하도록 하는 것이 목적이다. 문서는 어떤 연산을 제공하고 어떤 자료를 주고받는지 설명한다.
설명 형식과 본문 형식
OpenAPI 문서는 JSON 객체이며 JSON이나 YAML로 나타낼 수 있다. 이것이 실제 API의 요청과 응답 본문도 반드시 같은 형식이어야 한다는 뜻은 아니다.
도구가 활용하는 계약
같은 설명을 문서 생성과 클라이언트 및 서버 코드 생성, 테스트 도구에 사용할 수 있다. 명세는 인터페이스를 표현하는 규칙이며 실제 서비스가 그 설명대로 동작하는지는 구현과 검증의 영역이다.