이 페이지는 Cloud Translation API를 통해 번역되었습니다.

OpenAPI 3.x 기능 제한사항

이 문서에서는 API 게이트웨이와 함께 OpenAPI 3.x를 사용할 때의 기능 제한사항을 설명합니다.

지원되는 OpenAPI 사양 버전에 대한 자세한 내용은 OpenAPI 개요를 참고하세요.

새로운 OpenAPI 3.x 제한사항

이 섹션에서는 OpenAPI 3.x의 새로운 기능에 대한 제한사항을 설명합니다.

서버

OpenAPI 3.x는 호스트와 기본 경로를 정의하는 여러 server 객체를 지원합니다. 하지만 API 게이트웨이는 x-google-endpoint 확장 프로그램으로 식별되는 단일 서버 객체를 사용하여 서비스를 구성합니다.

여러 서버를 정의할 수 있지만 API Gateway는 x-google-endpoint 확장 프로그램을 포함하는 서버만 고려하며 이러한 서버는 하나만 허용됩니다. API 게이트웨이의 경우 서버 URL이 필요하지 않으므로 정의된 서버가 없거나 x-google-endpoint 확장 프로그램이 있는 서버가 하나 있을 수 있습니다.

예를 들어 API 게이트웨이의 경우 다음 정의가 유효합니다.

servers:
  - url: https://example.com
    x-google-endpoint: {}

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com

다음 정의는 x-google-endpoint 확장 프로그램이 여러 개 포함되어 있으므로 유효하지 않습니다.

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com
    x-google-endpoint: {}

다음 정의는 API 게이트웨이에 유효하지만 API 게이트웨이는 서버 객체를 무시합니다.

servers:
  - url: https://example.com

여러 파일에 걸쳐 있는 서버

OpenAPI 파일을 여러 개 업로드하고 한 파일에 x-google-endpoint 확장자가 있는 서버가 포함된 경우 모든 파일에도 동일한 x-google-endpoint 확장자와 서버 URL의 동일한 호스트로 정의된 서버가 있어야 합니다. 기본 경로는 파일마다 다를 수 있습니다.

상대 URL

API Gateway의 경우 사양에 호스트 이름이 필요하지 않으므로 servers 객체의 상대 URL은 자체 기본 경로로 처리됩니다. 이는 OpenAPI 정의를 호스팅하는 서버에 대해 상대 URL을 확인하는 표준 OpenAPI 동작과 다릅니다. 예를 들어 API Gateway는 url: /v1을 기본 경로로 취급합니다.

베이스 경로는 '/'로 시작해야 합니다. API Gateway는 스키마가 없거나 베이스 경로를 나타내기 위해 '/'로 시작하는 URL을 거부합니다.

지원되지 않는 확장 프로그램

API 게이트웨이는 OpenAPI 3.x의 x-google-allow 확장 프로그램을 지원하지 않습니다.

파일 크기 한도

API Gateway는 업로드된 OpenAPI 3.x 파일에 총 크기 제한 10MB와 파일 수 제한 50을 적용합니다.

기존 제한사항

이 섹션에서는 OpenAPI 2.0에서 이어져 OpenAPI 3.x에도 적용되는 제한사항을 설명합니다.

무시하는 범위

API Gateway는 보안 스키마 객체에 범위가 정의된 OpenAPI 문서를 수락하지만 API Gateway는 이러한 범위를 확인하거나 적용하지 않습니다.

여러 보안 요구사항

API 키 요구사항: 스키마 중 하나가 API 키인 경우 API Gateway는 대체 (논리합) 보안 요구사항을 지원하지 않습니다. 하지만 API 게이트웨이는 결합 (논리곱)을 지원하므로 API 키와 OAuth2 토큰을 모두 요구할 수 있습니다.
OAuth2 요구사항: API Gateway는 다양한 OAuth2 보안 스키마에 대한 대체 (논리합) 보안 요구사항을 지원합니다. 추가 보안 요구사항이 API 키가 아닌 경우 API 게이트웨이는 결합 (논리곱)을 지원하지 않습니다.
선택적 보안: 빈 보안 요구사항 (- {})을 사용하여 API 키에 대한 보안을 선택사항으로 만들 수 있지만 API Gateway는 OAuth에 대해 이를 지원하지 않습니다.

보안 정의 유효성 검사

API 게이트웨이는 securityDefinitions 섹션에 해당 정의가 없는 보안 요구사항을 사용하는 OpenAPI 3.x 사양을 거부합니다.

URL 경로 템플릿

API Gateway는 전체 경로 세그먼트를 나타내는 URL 경로 템플릿 매개변수(예: /items/{itemId})만 지원합니다. API Gateway는 부분 세그먼트에 해당하는 매개변수(예: /items/prefix_{id}_suffix)를 지원하지 않으며 거부합니다.

매개변수, 스키마, 요청 본문, 유형

API Gateway는 다양한 매개변수 및 유형 정의 (예: required 매개변수 및 배열 형식)가 포함된 OpenAPI 문서를 허용하지만 이를 강제하지는 않습니다. API 게이트웨이는 이러한 정의와 관계없이 수신 요청을 API로 전달합니다.

API Gateway는 요청 매개변수에서 기본 유형만 지원합니다.

외부 유형 참조

API Gateway는 제공된 OpenAPI 문서 외부의 유형에 대한 참조를 지원하지 않습니다. 예를 들어 API 게이트웨이는 외부 URL을 가리키는 $ref를 허용하지 않고 거부합니다.

호스트 주소의 커스텀 포트

API 게이트웨이는 OpenAPI 문서의 servers.url 필드에 커스텀 포트를 허용하지 않습니다.

YAML 별칭 제한사항

API 게이트웨이에 제출된 OpenAPI 문서에는 YAML 별칭 노드가 최대 200개까지 있을 수 있습니다.