Este documento descreve as limitações de recursos para usar a OpenAPI 3.x com o Endpoints.
Para mais informações sobre as versões da especificação OpenAPI com suporte, consulte Visão geral da OpenAPI.
Novas limitações da OpenAPI 3.x
Esta seção descreve as limitações da OpenAPI que são novas com o suporte da OpenAPI 3.x.
Servidores
A OpenAPI 3.x oferece suporte a vários objetos server para definir hosts e caminhos básicos. No entanto, o Cloud Endpoints usa apenas um objeto de servidor para configurar o nome do host e o caminho básico, identificado pela extensão x-google-endpoint.
Embora seja possível definir vários servidores na especificação da OpenAPI, o Cloud Endpoints usa apenas o servidor com a extensão x-google-endpoint. Você pode definir a extensão x-google-endpoint em apenas um servidor.
Para o Cloud Endpoints, um nome de host é obrigatório. Portanto, apenas um servidor precisa ter a extensão x-google-endpoint.
Por exemplo, as seguintes definições de servidor são válidas para o 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
A seguinte definição de servidor é inválida para o 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: {}
A seguinte definição também é inválida para o Cloud Endpoints:
servers:
- url: https://my-api.endpoints.my-project-id.cloud.goog
Servidores em vários arquivos
Se você fizer upload de vários arquivos da OpenAPI, todos eles precisarão seguir as limitações da seção servers. Se um arquivo contiver um servidor com a extensão x-google-endpoint, todos os arquivos precisarão definir um servidor com uma extensão x-google-endpoint.
Além disso, todos os servidores com a extensão x-google-endpoint precisam usar um host idêntico no URL do servidor, e a configuração x-google-endpoint precisa ser idêntica em todos os arquivos. O caminho básico no URL do servidor pode ser diferente.
URL relativo
O Cloud Endpoints exige um nome de host. Portanto, ele não oferece suporte a URLs relativos.
Extensões incompatíveis
A OpenAPI 3.x não oferece suporte à extensão x-google-allow.
Limitações preexistentes
Esta seção descreve as limitações que existiam na OpenAPI 2.0 e continuam a ser aplicadas à OpenAPI 3.x.
Escopos ignorados
Embora seja possível definir escopos em um objeto de esquema de segurança, o ESP ou o Cloud Endpoints Frameworks não os verificam.
Vários requisitos de segurança
É possível especificar mais de um requisito de segurança no documento do OpenAPI.
Requisitos de segurança com uma chave de API: o Cloud Endpoints não oferece suporte a requisitos de segurança alternativos (OR lógico) quando um dos esquemas é uma chave de API. O Cloud Endpoints oferece suporte a conjunções (AND lógico), para que você possa exigir uma chave de API e a autenticação do OAuth2.
Requisitos de segurança para OAuth2: o Cloud Endpoints oferece suporte a requisitos de segurança alternativos (OR lógico) para diferentes esquemas de autenticação OAuth2. O Cloud Endpoints não oferece suporte a conjunções (AND lógico), a menos que o requisito de segurança adicional seja uma chave de API.
Requisitos de segurança opcionais: a OpenAPI 3 oferece suporte à segurança opcional, incluindo um requisito vazio (
{}). A chave de API oferece suporte a isso, mas o OAuth não.
Validação da definição de segurança
Para a OpenAPI 3.x, o uso de um esquema de segurança indefinido resulta em um erro, e o Cloud Endpoints rejeita a especificação. Essa é uma mudança da OpenAPI 2.0, em que isso só produzia um alerta.
Modelos do caminho do URL
O Cloud Endpoints oferece suporte apenas a parâmetros de modelo de caminho de URL que correspondem a segmentos de caminho inteiros (delimitados por /). O Cloud Endpoints não oferece suporte a parâmetros para segmentos de caminho parciais.
Por exemplo, o Cloud Endpoints oferece suporte a /items/{itemId}, mas não a /items/overview.{format}.
Operações no caminho raiz do URL /
Embora o documento da OpenAPI aceite operações no caminho raiz /, o Extensible Service Proxy rejeita solicitações para o caminho raiz. Essa limitação não se aplica ao ESPv2, que oferece suporte ao caminho raiz.
Parâmetros, esquemas, corpos de solicitação e tipos
O Extensible Service Proxy e o ESP ignoram a maioria das definições de parâmetro, esquema, corpo da solicitação e tipo. O Extensible Service Proxy e o ESP não aplicam parâmetros obrigatórios e definições de tipo, e encaminham solicitações para sua API.
O Extensible Service Proxy e o ESP oferecem suporte apenas a tipos primitivos em parâmetros de solicitação.
Referências de tipo externo
O Cloud Endpoints não oferece suporte a referências a tipos fora do documento da OpenAPI. Por exemplo, não é possível usar um $ref para um URL externo.
Porta personalizada no endereço do host de serviço
Não é possível usar portas personalizadas no url de um objeto servers.
Limitações de alias do YAML
Um documento da OpenAPI pode conter no máximo 200 nós de alias do YAML.
Corpo da solicitação não repetido
É possível definir apenas um requestBody por operação, e ele precisa ser de um tipo não repetido.