OpenAPI는 HTTP [[API]]의 구조를 기술하는 명세다. 요청 주소와 매개변수, 응답, 보안 요구사항을 기계가 읽을 수 있는 문서로 표현한다. ([OpenAPI 3.1.1 명세](https://spec.openapis.org/oas/v3.1.1.html))

- API의 동작을 실제로 구현하는 서버와 명세 문서는 구분한다. 문서가 유효하더라도 서버가 그 약속대로 응답하는지는 별도로 확인해야 한다. ([명세의 목적과 범위](https://spec.openapis.org/oas/v3.1.1.html))
- `paths`에는 주소별 작업을, `responses`에는 결과를 기술한다. [[API 문서]] 생성이나 클라이언트 코드 생성에 이 정보를 활용할 수 있다. ([경로와 응답 객체](https://spec.openapis.org/oas/v3.1.1.html))
- 여러 작업이 공유하는 스키마는 `components`에 두고 [[참조 객체]]로 연결할 수 있다. 같은 구조를 매번 복사해서 다른 설명으로 갈라지는 일을 줄인다. ([컴포넌트와 참조](https://spec.openapis.org/oas/v3.1.1.html))

## 기타 등등

- 명세의 `openapi` 버전과 API 자체를 소개하는 `info.version`은 다른 값이다. [출처](https://spec.openapis.org/oas/v3.1.1.html)
- OpenAPI 3.1의 스키마 객체는 JSON Schema의 어휘를 기반으로 한다. [출처](https://spec.openapis.org/oas/v3.1.1.html)

#API #표준 #문서화