Se usó la API de Cloud Translation para traducir esta página.

Limitaciones de las características de OpenAPI 3.x

En este documento, se describen las limitaciones de las funciones para usar OpenAPI 3.x con API Gateway.

Para obtener más información sobre las versiones compatibles de la especificación de OpenAPI, consulta Descripción general de OpenAPI.

Nuevas limitaciones de OpenAPI 3.x

En esta sección, se describen las limitaciones de las funciones nuevas en OpenAPI 3.x.

Servidores

OpenAPI 3.x admite varios objetos server para definir hosts y rutas de acceso base. Sin embargo, API Gateway se basa en un solo objeto de servidor, identificado por la extensión x-google-endpoint, para configurar el servicio.

Si bien puedes definir varios servidores, API Gateway solo considera el servidor que contiene la extensión x-google-endpoint y permite solo uno de esos servidores. En el caso de API Gateway, no se requiere una URL de servidor, por lo que puedes no tener servidores definidos o tener un servidor con la extensión x-google-endpoint.

Por ejemplo, las siguientes definiciones son válidas para API Gateway:

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

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

La siguiente definición no es válida porque contiene varias extensiones x-google-endpoint:

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

La siguiente definición es válida para API Gateway, pero API Gateway ignora el objeto del servidor:

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

Servidores en varios archivos

Si subes varios archivos de OpenAPI y uno de ellos contiene un servidor con la extensión x-google-endpoint, todos los archivos también deben tener un servidor definido con una extensión x-google-endpoint idéntica y un host idéntico en la URL del servidor. La ruta base puede variar entre los archivos.

URL relativa

En el caso de API Gateway, las URLs relativas del objeto servers se tratan como una ruta base por sí solas, ya que no se requiere un nombre de host en la especificación. Esto es diferente del comportamiento estándar de OpenAPI, que resuelve las URLs relativas con respecto al servidor que aloja la definición de OpenAPI. Por ejemplo, API Gateway trata url: /v1 como una ruta base.

Las rutas base deben comenzar con "/". API Gateway rechaza las URLs que no tienen un esquema o que comienzan con "/" para indicar una ruta base.

Extensiones no admitidas

API Gateway no admite la extensión x-google-allow para OpenAPI 3.x.

Límites de tamaño de archivo

API Gateway aplica un límite de tamaño total de 10 MB y un límite de recuento de archivos de 50 para los archivos OpenAPI 3.x subidos.

Limitaciones preexistentes

En esta sección, se describen las limitaciones heredadas de OpenAPI 2.0 que también se aplican a OpenAPI 3.x.

Alcances ignorados

Aunque API Gateway acepta documentos de OpenAPI con alcances definidos en un objeto de esquema de seguridad, API Gateway no verifica ni aplica estos alcances.

Varios requisitos de seguridad

Requisitos de la clave de API: API Gateway no admite requisitos de seguridad alternativos (OR lógico) si uno de los esquemas es una clave de API. Sin embargo, API Gateway admite conjunciones (operador lógico AND), lo que te permite requerir tanto una clave de API como un token de OAuth2.
Requisitos de OAuth2: API Gateway admite requisitos de seguridad alternativos (OR lógico) para diferentes esquemas de seguridad de OAuth2. API Gateway no admite conjunciones (operador lógico AND), a menos que el requisito de seguridad adicional sea una clave de API.
Seguridad opcional: Puedes usar un requisito de seguridad vacío (- {}) para que la seguridad sea opcional para una clave de API, pero API Gateway no admite esto para OAuth.

Validación de la definición de seguridad

API Gateway rechazará una especificación de OpenAPI 3.x que use un requisito de seguridad sin una definición correspondiente en la sección securityDefinitions.

Plantillas de ruta de URL

API Gateway solo admite parámetros de plantilla de ruta de URL que representan segmentos de ruta completos, por ejemplo, /items/{itemId}. API Gateway no admite ni rechaza parámetros correspondientes a segmentos parciales, por ejemplo, /items/prefix_{id}_suffix.

Parámetros, esquemas, cuerpos de la solicitud y tipos

API Gateway acepta documentos de OpenAPI con varias definiciones de parámetros y tipos (por ejemplo, parámetros required y formatos de array), pero no los aplica. API Gateway reenvía las solicitudes entrantes a tu API independientemente de estas definiciones.

API Gateway solo admite tipos primitivos en los parámetros de solicitud.

Referencias a tipos externos

API Gateway no admite referencias a tipos fuera del documento de OpenAPI proporcionado. Por ejemplo, API Gateway no permite ni rechaza un $ref que apunta a una URL externa.

Puerto personalizado en la dirección del host

API Gateway no permite puertos personalizados en el campo servers.url de un documento de OpenAPI.

Limitaciones de alias de YAML

Un documento de OpenAPI enviado a API Gateway puede tener un máximo de 200 nodos de alias de YAML.