OpenAPI 버전

OpenAPI 버전 (OpenAPI Versions)

OpenAPI 명세는 시간이 지나며 버전이 올라갔어요. 각 버전이 어떤 차이를 갖는지 알면, 기존 명세를 마이그레이션 하거나 최신 기능을 골라 쓸 때 헷갈리지 않아요.

출처: https://swagger.io/docs/specification/versions/

현재 크게 세 갈래로 나뉘어요.

  • OpenAPI 2.0(Swagger 2.0): 이전 세대 명세예요. swagger: "2.0"을 루트 키로 쓰고, 보안 정의가 securityDefinitions, 기본 인증이 type: basic이었어요.
  • OpenAPI 3.0 (3.0.0 ~ 3.0.4): 구조가 크게 바뀐 버전이에요. 보안 정의가 components.securitySchemes로 옮겨지고 type: basic이 type: http + scheme: basic으로 바뀌었으며, 쿠키 인증·여러 서버(servers)·파일 업로드·oneOf/anyOf/allOf 같은 구성 조합(composition)이 추가됐어요.
  • OpenAPI 3.1: 3.0의 후속으로, JSON Schema Draft 2020-12와 완전히 호환되는 스키마를 쓰는 게 가장 큰 변화예요. nullable 대신 type: ["string", "null"]과 JSON Schema 방식의 example(복수) 처럼 표현이 통일됐어요. 단, 회귀로서 type이 배열이 될 수 있고 여러 JSON Schema 키워드 지원이 달라져, 3.0과 3.1을 오갈 땐 주의가 필요해요.

스펙의 버전 선택은 단순히 "최신이니까"보다 도구 생태계와의 호환성이 중요해요. 예를 들어 여전히 많은 툴체인이 OpenAPI 3.0 예제를 기본으로 하는 경우가 많아요. 명세를 새로 시작한다면 3.1의 JSON Schema 2020-12 호환성을 고려해서, 팀이 쓰는 코드 생성기·테스트 도구가 어떤 버전을 제대로 지원하는지 확인하는 게 좋아요.

이 문서처럼 스펙 버전을 명시하면 "이 정의가 어떤 규칙으로 쓰였는지"를 머신이 알 수 있고, 그게 문서화·검증 도구가 명세를 올바르게 해석하는 출발점이 돼요.

더 알아보기