En este documento se describen las limitaciones de las funciones al usar OpenAPI 3.x con Endpoints.
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 OpenAPI que son nuevas con la compatibilidad con OpenAPI 3.x.
Servers (Servidores)
OpenAPI 3.x admite varios objetos server para definir hosts y rutas base. Sin embargo, Cloud Endpoints solo usa un objeto de servidor para configurar el nombre de host y la ruta base, que se identifica mediante la extensión x-google-endpoint.
Aunque 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 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 tampoco 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 OpenAPI, todos deben cumplir 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 ser diferente.
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.
Permisos ignorados
Aunque puede definir ámbitos en un objeto de esquema de seguridad, ESP o Cloud Endpoints Frameworks no los comprueban.
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 (AND lógico), por lo que puedes requerir tanto una clave de API como la autenticación OAuth 2.0.
Requisitos de seguridad de OAuth2: Cloud Endpoints admite requisitos de seguridad alternativos (OR lógico) para diferentes esquemas de autenticación OAuth2. Cloud Endpoints no admite conjunciones (AND lógico) a menos que el requisito de seguridad adicional sea una clave de API.
Requisitos de seguridad opcionales: OpenAPI 3 admite la seguridad opcional incluyendo un requisito vacío (
{}). La clave de API admite esta opción, pero OAuth no.
Validación de la definición de seguridad
En OpenAPI 3.x, si se usa un esquema de seguridad indefinido, se produce un error y Cloud Endpoints rechaza la especificación. Esto supone un cambio respecto a OpenAPI 2.0, donde solo se mostraba una advertencia.
Creación de 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 de segmentos de ruta parciales.
Por ejemplo, Cloud Endpoints admite /items/{itemId}, pero no /items/overview.{format}.
Operaciones en la ruta raíz de la URL /
Aunque el documento de OpenAPI acepta operaciones en la ruta raíz /, Extensible Service Proxy rechaza las solicitudes a la ruta raíz. Esta limitación no se aplica a ESPv2, que admite la ruta raíz.
Parámetros, esquemas, cuerpos de solicitud y tipos
El proxy de servicios extensible (ESP) ignora la mayoría de los parámetros, esquemas, cuerpos de solicitud y definiciones de tipo. Extensible Service Proxy y ESP no aplican los parámetros obligatorios ni las definiciones de tipo, y reenvían las solicitudes a tu API.
Extensible Service Proxy y ESP solo admiten tipos primitivos en los parámetros de solicitud.
Referencias de tipos externos
Cloud Endpoints no admite referencias a tipos que no estén incluidos en el documento de OpenAPI. Por ejemplo, no puedes usar un $ref para una URL externa.
Puerto personalizado en la dirección del host del servicio
No puedes usar puertos personalizados en el url de un objeto servers.
Limitaciones de los alias de YAML
Un documento OpenAPI puede contener un máximo de 200 nodos de alias YAML.
Cuerpo de la solicitud no repetitivo
Solo puedes definir un requestBody por operación, y debe ser de un tipo no repetitivo.