OpenAPI Specification의 핵심 구조
OpenAPI 문서는 루트 객체(openapi, info, servers, paths, components)와 재사용 가능한 스키마 정의로 구성됩니다. paths 객체는 상대 URL 경로를 HTTP 메서드(get, post, put, delete 등)의 Operation 객체에 매핑하고, 각 Operation은 parameters, requestBody, responses를 선언합니다. components 객체는 중복을 피하기 위해 재사용 가능한 스키마, 매개변수, 응답을 저장소로 제공합니다.
매개변수와 요청/응답 스키마 관리
OpenAPI 3.0+에서 매개변수는 path, query, header, cookie 위치 중 하나에서 정의되며, requestBody는 이전의 body 매개변수를 대체하여 content 객체(MIME 타입별 스키마)를 통해 복잡한 페이로드를 명시적으로 기술합니다. Schema 객체는 JSON Schema 기반이지만 OpenAPI 확장(nullable, discriminator, readOnly/writeOnly)을 포함하여, 요청/응답 데이터 구조를 정확하게 검증하고 코드 생성 도구에 제공합니다.
Swagger 2.0과의 진화 과정
Swagger 2.0(OpenAPI 2.0)은 단일 swagger: "2.0" 필드와 host, basePath, schemes로 서버 정보를 분산했으나, OpenAPI 3.0+는 servers 배열로 통합하고, formData 매개변수를 폐기하고 명시적 requestBody 객체를 도입했습니다. 또한 Components 객체 도입, Callback/Link 객체 추가 등으로 보다 복잡한 API 계약을 표현할 수 있게 발전했습니다.