Esta página se ha traducido con Cloud Translation API.

Limitaciones de las funciones de OpenAPI 3.x

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

Para obtener más información sobre las versiones admitidas de la especificación de OpenAPI, consulta el artículo Información general sobre OpenAPI.

Nuevas limitaciones de OpenAPI 3.x

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

Servers (Servidores)

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

Aunque puedes definir varios servidores, API Gateway solo tiene en cuenta el servidor que contiene la extensión x-google-endpoint y solo permite un servidor de este tipo. En el caso de API Gateway, no es necesario especificar una URL de servidor, por lo que puedes no definir ningún servidor o definir 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 de servidor:

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

Servidores en varios archivos

Si subes varios archivos 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 archivos.

URL relativa

En 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 en el servidor que aloja la definición de OpenAPI. Por ejemplo, API Gateway trata url: /v1 como una ruta base.

Las rutas base deben empezar por "/". API Gateway rechaza las URLs que no tienen un esquema o que empiezan por "/" 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 los archivos

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

Limitaciones preexistentes

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

Permisos ignorados

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

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 (AND lógico), 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 (AND lógico) 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 esta opción para OAuth.

Validación de la definición de seguridad

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

Creación de plantillas de ruta de URL

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

Parámetros, esquemas, cuerpos de 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 matriz), 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 de tipos externos

API Gateway no admite referencias a tipos que no estén incluidos en el documento OpenAPI proporcionado. Por ejemplo, API Gateway no permite ni rechaza un $ref que apunte a una URL externa.

Puerto personalizado en la dirección de host

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

Limitaciones de los alias de YAML

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