OpenAPI는 HTTP API의 구조와 사용 계약을 도구가 읽을 수 있는 문서로 표현하는 명세다. 경로, 메서드, 입력값, 응답, 인증 방식 등을 기술하며 문서 화면이나 클라이언트 코드 생성에 활용할 수 있다. API 서버를 실행하는 프로토콜 자체와는 구분된다. OpenAPI 공식 명세
문서에 담는 내용
REST API에서 문서를 생성하는 작업을 공개한다면, 제목이 필수인지, 본문은 문자열인지, 어떤 성공·오류 응답이 있는지 명확히 적어야 한다. JSON이나 YAML 형태로 표현할 수 있으며 공통 구조는 재사용해 반복을 줄인다. 경로·질의 인자와 요청 본문의 구분은 OpenAPI 입력 구조 안내에서 확인할 수 있다.
| 구성 | 예시 내용 |
|---|---|
| 서버와 경로 | API 기준 주소와 /articles |
| 작업 | 문서 생성 POST |
| 요청 구조 | title, content, locale |
| 응답 구조 | 문서 식별자와 처리 상태 |
| 보안 정의 | 필요한 인증 방식 |
명세 버전과 API 제품의 버전은 서로 다른 정보다. 예를 들어 사용하는 OpenAPI 문법의 버전이 바뀌었다고 제품의 공개 API가 반드시 달라지는 것은 아니다.
자동화에 사용하는 방식
문서에서 입력 폼을 생성하거나 샘플 요청을 보여주고, 언어별 클라이언트를 생성하는 도구를 연결할 수 있다. CI에서 명세 문법을 검사하고 구현 응답과 비교하면 문서가 뒤처지는 문제를 줄인다. 계약을 먼저 논의한 뒤 서버와 클라이언트를 병렬로 개발할 때도 도움이 된다.
기술할 수 있어도 실행되는 것은 아니다
인증 요구를 문서에 적는 것만으로 서버에 권한 검사가 생기지는 않는다. 예시 응답도 실행 결과의 증거가 아니다. 실제 입력 검증과 오류 처리는 서버가 구현하고 통합 테스트로 확인해야 한다.
특히 선택 필드와 필수 필드, null과 누락, 페이지네이션과 재시도 규칙을 구분해야 한다. 업무 규칙을 설명 문장에만 숨기지 말고 표현 가능한 제약은 스키마로 남겨 도구와 사람이 같은 계약을 이해하도록 한다.