API 문서는 [[API]]를 호출하는 방법과 입력·출력·오류 조건을 설명하는 자료다. HTTP API의 경우 주소와 메서드, 매개변수, 응답 형식을 함께 다룬다. ([OpenAPI 명세](https://spec.openapis.org/oas/v3.1.1.html))

- 성공 응답만 보여주면 실패했을 때의 처리를 알 수 없다. 필수 입력과 인증 방식, 가능한 응답 코드를 함께 제시한다. ([매개변수·보안·응답 객체](https://spec.openapis.org/oas/v3.1.1.html))
- 예시는 실제 스키마와 맞아야 한다. 문서의 예시를 복사했는데 필수 값이 빠져 있으면, 시작하려던 사람이 먼저 문서를 고쳐야 한다. ([OpenAPI의 예시 객체](https://spec.openapis.org/oas/v3.1.1.html))
- [[OpenAPI]]는 HTTP API의 구조를 기계가 읽을 수 있게 기술한다. 이 명세를 문서 생성과 클라이언트 코드 생성 등에 활용할 수 있다. ([OpenAPI의 목적](https://spec.openapis.org/oas/v3.1.1.html))

## 기타 등등

- OpenAPI 문서는 JSON 또는 YAML로 표현할 수 있다. [출처](https://spec.openapis.org/oas/v3.1.1.html)
- 명세에는 더는 사용을 권장하지 않는 작업을 표시하는 `deprecated` 필드도 있다. [출처](https://spec.openapis.org/oas/v3.1.1.html)

#API #문서화 #웹개발