이 문서에서는 Endpoints와 함께 OpenAPI 3.x를 사용할 때의 기능 제한사항을 설명합니다.
지원되는 OpenAPI 사양 버전에 대한 자세한 내용은 OpenAPI 개요를 참고하세요.
새로운 OpenAPI 3.x 제한사항
이 섹션에서는 OpenAPI 3.x 지원으로 새로 도입된 OpenAPI의 제한사항을 설명합니다.
서버
OpenAPI 3.x는 호스트와 기본 경로를 정의하는 여러 server 객체를 지원합니다. 하지만 Cloud Endpoints는 x-google-endpoint 확장 프로그램으로 식별되는 호스트 이름과 기본 경로를 구성하는 데 단일 서버 객체만 사용합니다.
OpenAPI 사양에서 여러 서버를 정의할 수 있지만 Cloud Endpoints는 x-google-endpoint 확장 프로그램이 있는 서버만 사용합니다. 하나의 서버에서만 x-google-endpoint 확장 프로그램을 정의할 수 있습니다.
Cloud Endpoints의 경우 호스트 이름이 필요하므로 서버 하나에만 x-google-endpoint 확장 프로그램이 있어야 합니다.
예를 들어 다음 서버 정의는 Cloud Endpoints에 유효합니다.
servers:
- url: https://my-api.endpoints.my-project-id.cloud.goog
x-google-endpoint: {}
servers:
- url: https://my-api.endpoints.my-project-id.cloud.goog
x-google-endpoint: {}
- url: https://example.com
다음 서버 정의는 Endpoints에서 유효하지 않습니다.
servers:
- url: https://my-api-1.endpoints.my-project-id.cloud.goog
x-google-endpoint: {}
- url: https://my-api-2.endpoints.my-project-id.cloud.goog
x-google-endpoint: {}
다음 정의도 Cloud Endpoints에 유효하지 않습니다.
servers:
- url: https://my-api.endpoints.my-project-id.cloud.goog
여러 파일에 걸친 서버
OpenAPI 파일을 여러 개 업로드하는 경우 모든 파일이 servers 섹션 제한사항을 따라야 합니다. 한 파일에 x-google-endpoint 확장자가 있는 서버가 포함된 경우 모든 파일에서 x-google-endpoint 확장자가 있는 서버를 정의해야 합니다.
또한 x-google-endpoint 확장자가 있는 모든 서버는 서버 URL에서 동일한 호스트를 사용해야 하며 x-google-endpoint 구성은 모든 파일에서 동일해야 합니다. 서버 URL의 기본 경로는 다를 수 있습니다.
상대 URL
Cloud Endpoints에는 호스트 이름이 필요하므로 상대 URL은 지원되지 않습니다.
지원되지 않는 확장 프로그램
OpenAPI 3.x는 x-google-allow 확장 프로그램을 지원하지 않습니다.
기존 제한사항
이 섹션에서는 OpenAPI 2.0에 있었으며 OpenAPI 3.x에도 계속 적용되는 제한사항을 설명합니다.
무시하는 범위
보안 스키마 객체에서 범위를 정의할 수 있지만 ESP 또는 Cloud Endpoints Frameworks는 이를 확인하지 않습니다.
여러 보안 요구사항
OpenAPI 문서에서 여러 개의 보안 요구사항을 지정할 수 있습니다.
API 키가 있는 보안 요구사항: Cloud Endpoints는 스키마 중 하나가 API 키일 때 대체 (논리합) 보안 요구사항을 지원하지 않습니다. Cloud Endpoints는 결합 (논리곱)을 지원하므로 API 키와 OAuth2 인증을 모두 요구할 수 있습니다.
OAuth2의 보안 요구사항: Cloud Endpoints는 다양한 OAuth2 인증 스키마에 대한 대체 (논리합) 보안 요구사항을 지원합니다. 추가 보안 요구사항이 API 키가 아닌 경우 Cloud Endpoints는 결합 (논리곱)을 지원하지 않습니다.
선택적 보안 요구사항: OpenAPI 3는 빈 요구사항 (
{})을 포함하여 선택적 보안을 지원합니다. API 키는 이를 지원하지만 OAuth는 지원하지 않습니다.
보안 정의 유효성 검사
OpenAPI 3.x의 경우 정의되지 않은 보안 스키마를 사용하면 오류가 발생하고 Cloud Endpoints에서 사양을 거부합니다. 이는 경고만 생성했던 OpenAPI 2.0에서 변경된 사항입니다.
URL 경로 템플릿
Cloud Endpoints는 전체 경로 세그먼트 (/로 구분됨)에 해당하는 URL 경로 템플릿 매개변수만 지원합니다. 부분 경로 세그먼트의 매개변수는 지원되지 않습니다.
예를 들어 Cloud Endpoints는 /items/{itemId}를 지원하지만 /items/overview.{format}는 지원하지 않습니다.
URL 루트 경로 /에서의 작업
OpenAPI 문서는 루트 경로 /에서의 작업을 허용하지만 확장 가능 서비스 프록시는 루트 경로에 대한 요청을 거부합니다. 이 제한은 루트 경로를 지원하는 ESPv2에는 적용되지 않습니다.
매개변수, 스키마, 요청 본문, 유형
Extensible Service Proxy 및 ESP는 대부분의 매개변수, 스키마, 요청 본문, 유형 정의를 무시합니다. 확장 가능 서비스 프록시와 ESP는 필수 매개변수 및 유형 정의를 강제하지 않으며 요청을 API로 전달합니다.
확장 가능 서비스 프록시와 ESP는 요청 매개변수에서 기본 유형만 지원합니다.
외부 유형 참조
Cloud Endpoints는 OpenAPI 문서 외부의 유형에 대한 참조를 지원하지 않습니다. 예를 들어 외부 URL에 $ref를 사용할 수 없습니다.
서비스 호스트 주소의 커스텀 포트
servers 객체의 url에서 커스텀 포트를 사용할 수 없습니다.
YAML 별칭 제한사항
OpenAPI 문서에는 최대 200개의 YAML 별칭 노드가 포함될 수 있습니다.
반복되지 않는 요청 본문
작업당 하나의 requestBody만 정의할 수 있으며 반복되지 않는 유형이어야 합니다.