En este documento, se describen las limitaciones de las funciones para usar OpenAPI 3.x con Endpoints.
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 OpenAPI que son nuevas con la compatibilidad con OpenAPI 3.x.
Servidores
OpenAPI 3.x admite varios objetos server para definir hosts y rutas de acceso base. Sin embargo, Cloud Endpoints solo usa un objeto de servidor para configurar el nombre de host y la ruta de acceso base, identificados por la extensión x-google-endpoint.
Si bien puedes definir varios servidores en tu especificación de OpenAPI, Cloud Endpoints solo usa el servidor con la extensión x-google-endpoint. Solo puedes definir la extensión x-google-endpoint en un servidor.
En el caso de Cloud Endpoints, se requiere un nombre de host, por lo que solo un servidor debe tener la extensión x-google-endpoint.
Por ejemplo, las siguientes definiciones de servidor son válidas para 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
La siguiente definición del servidor no es válida para 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: {}
La siguiente definición también es inválida para Cloud Endpoints:
servers:
- url: https://my-api.endpoints.my-project-id.cloud.goog
Servidores en varios archivos
Si subes varios archivos de OpenAPI, todos deben cumplir con las limitaciones de la sección servers. Si un archivo contiene un servidor con la extensión x-google-endpoint, todos los archivos deben definir un servidor con la extensión x-google-endpoint.
Además, todos los servidores con la extensión x-google-endpoint deben usar un host idéntico en la URL del servidor, y la configuración de x-google-endpoint debe ser idéntica en todos los archivos. La ruta base de la URL del servidor puede variar.
URL relativa
Cloud Endpoints requiere un nombre de host, por lo que no admite URLs relativas.
Extensiones no admitidas
OpenAPI 3.x no admite la extensión x-google-allow.
Limitaciones preexistentes
En esta sección, se describen las limitaciones que existían en OpenAPI 2.0 y que se siguen aplicando a OpenAPI 3.x.
Alcances ignorados
Aunque puedes definir alcances en un objeto de esquema de seguridad, ESP o Cloud Endpoints Frameworks no los verifican.
Varios requisitos de seguridad
Puedes especificar más de un requisito de seguridad en tu documento de OpenAPI.
Requisitos de seguridad con una clave de API: Cloud Endpoints no admite requisitos de seguridad alternativos (OR lógico) cuando uno de los esquemas es una clave de API. Cloud Endpoints admite conjunciones (operador lógico AND), por lo que puedes requerir tanto una clave de API como autenticación OAuth2.
Requisitos de seguridad para OAuth2: Cloud Endpoints admite requisitos de seguridad alternativos (OR lógico) para diferentes esquemas de autenticación de OAuth2. Cloud Endpoints no admite conjunciones (operador lógico AND), a menos que el requisito de seguridad adicional sea una clave de API.
Requisitos de seguridad opcionales: OpenAPI 3 admite la seguridad opcional con la inclusión de un requisito vacío (
{}). La clave de API admite esto, pero OAuth no.
Validación de la definición de seguridad
En el caso de OpenAPI 3.x, usar un esquema de seguridad no definido genera un error, y Cloud Endpoints rechaza la especificación. Este es un cambio con respecto a OpenAPI 2.0, en el que solo se producía una advertencia.
Plantillas de ruta de URL
Cloud Endpoints solo admite parámetros de plantilla de ruta de URL que corresponden a segmentos de ruta completos (delimitados por /). Cloud Endpoints no admite parámetros para segmentos de ruta parciales.
Por ejemplo, Cloud Endpoints admite /items/{itemId}, pero no /items/overview.{format}.
Operaciones en la ruta de acceso raíz de URL /
Si bien el documento de OpenAPI acepta operaciones en la ruta raíz /, el proxy de servicio extensible rechaza las solicitudes a la ruta raíz. Esta limitación no se aplica a ESPv2, que admite la ruta de acceso raíz.
Parámetros, esquemas, cuerpos de la solicitud y tipos
El proxy de servicio extensible y el ESP ignoran la mayoría de las definiciones de parámetros, esquemas, cuerpos de solicitudes y tipos. El proxy de servicio extensible y el ESP no aplican los parámetros obligatorios ni las definiciones de tipos, y reenvían las solicitudes a tu API.
El proxy de servicio extensible y el ESP solo admiten tipos primitivos en los parámetros de solicitud.
Referencias a tipos externos
Cloud Endpoints no admite referencias a tipos fuera del documento de OpenAPI. Por ejemplo, no puedes usar un $ref a una URL externa.
Puerto personalizado en una dirección de host de servicio
No puedes usar puertos personalizados en el url de un objeto servers.
Limitaciones de alias de YAML
Un documento de OpenAPI puede contener un máximo de 200 nodos de alias de YAML.
Cuerpo de la solicitud no repetitivo
Solo puedes definir un requestBody por operación, y debe ser de un tipo no repetitivo.