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. Puedes definir la extensión x-google-endpoint en un solo 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 de 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 no es vá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 seguir 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 una 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 x-google-endpoint debe ser idéntica en todos los archivos. La ruta de acceso base en la URL del servidor puede diferir.
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, el 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 (operador lógico OR) 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 (operador lógico OR) para diferentes esquemas de autenticación 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 seguridad opcional mediante 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, el uso de 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 esto solo 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 de acceso completos (delimitados por /). Cloud Endpoints no admite parámetros para segmentos de ruta de acceso 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 de acceso raíz /, el proxy de servicio extensible rechaza las solicitudes a la ruta de acceso raíz. Esta limitación no se aplica a ESPv2, que admite la ruta de acceso raíz.
Parámetros, esquemas, cuerpos de solicitud y tipos
El proxy de servicio extensible y el ESP ignoran la mayoría de las definiciones de parámetros, esquemas, cuerpos de solicitud y tipos. El proxy de servicio extensible y el ESP no aplican los parámetros obligatorios ni las definiciones de tipo, y reenvían las solicitudes a tu API.
El proxy de servicio extensible y el ESP solo admiten tipos básicos 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 en una URL externa.
Puerto personalizado en una dirección de host de servicio
No puedes usar puertos personalizados en la 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 solicitud no repetitivo
Solo puedes definir un requestBody por operación, y debe ser de un tipo no repetitivo.