Este documento descreve as limitações das funcionalidades para usar a OpenAPI 3.x com os Endpoints.
Para mais informações sobre as versões da especificação OpenAPI suportadas, consulte o artigo Vista geral da OpenAPI.
Novas limitações da OpenAPI 3.x
Esta secção descreve as limitações do OpenAPI que são novas com o suporte do OpenAPI 3.x.
Servidores
O OpenAPI 3.x suporta vários objetos server para definir anfitriões e caminhos base. No entanto, o Cloud Endpoints usa apenas um objeto de servidor para configurar o nome do anfitrião e o caminho base, identificados pela extensão x-google-endpoint.
Embora possa definir vários servidores na especificação OpenAPI, o Cloud Endpoints usa apenas o servidor com a extensão x-google-endpoint. Só pode definir a extensão x-google-endpoint num servidor.
Para os Cloud Endpoints, é necessário um nome do anfitrião, pelo que apenas um servidor tem de 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 os 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 ficheiros
Se carregar vários ficheiros OpenAPI, todos os ficheiros têm de seguir as limitações da secção servers. Se um ficheiro contiver um servidor com a extensão x-google-endpoint, todos os ficheiros têm de definir um servidor com uma extensão x-google-endpoint.
Além disso, todos os servidores com a extensão x-google-endpoint têm de usar um anfitrião idêntico no URL do servidor, e a configuração x-google-endpoint tem de ser idêntica em todos os ficheiros. O caminho base no URL do servidor pode ser diferente.
URL relativo
O Cloud Endpoints requer um nome de anfitrião, pelo que não suporta URLs relativos.
Extensões não suportadas
O OpenAPI 3.x não suporta a extensão x-google-allow.
Limitações pré-existentes
Esta secção descreve as limitações que existiam no OpenAPI 2.0 e continuam a aplicar-se ao OpenAPI 3.x.
Âmbitos ignorados
Embora possa definir âmbitos num objeto de esquema de segurança, o ESP ou os frameworks do Cloud Endpoints não os verificam.
Vários requisitos de segurança
Pode especificar mais do que um requisito de segurança no seu documento OpenAPI.
Requisitos de segurança com uma chave de API: o Cloud Endpoints não suporta requisitos de segurança alternativos (OR lógico) quando um dos esquemas é uma chave de API. O Cloud Endpoints suporta conjunções (AND lógico), pelo que pode exigir uma chave da API e a autenticação OAuth2.
Requisitos de segurança para o OAuth2: os Cloud Endpoints suportam requisitos de segurança alternativos (OR lógico) para diferentes esquemas de autenticação OAuth2. O Cloud Endpoints não suporta 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 suporta segurança opcional através da inclusão de um requisito vazio (
{}). A chave da API suporta esta opção, mas o OAuth não.
Validação da definição de segurança
Para o OpenAPI 3.x, a utilização de um esquema de segurança indefinido resulta num erro, e o Cloud Endpoints rejeita a especificação. Esta é uma alteração em relação à OpenAPI 2.0, em que esta ação apenas produzia um aviso.
Criação de modelos de caminhos de URLs
O Cloud Endpoints suporta apenas parâmetros de modelo de caminho de URL que correspondam a segmentos de caminho completos (delimitados por /). O Cloud Endpoints não suporta parâmetros para segmentos de caminho parciais.
Por exemplo, o Cloud Endpoints suporta /items/{itemId}, mas não suporta /items/overview.{format}.
Operações no caminho raiz do URL /
Embora o documento OpenAPI aceite operações no caminho raiz /, o proxy de serviço extensível rejeita pedidos para o caminho raiz. Esta limitação não se aplica ao ESPv2, que suporta o caminho raiz.
Parâmetros, esquemas, corpos de pedidos e tipos
O proxy de serviço extensível e o ESP ignoram a maioria das definições de parâmetros, esquemas, corpo do pedido e tipos. O proxy de serviço extensível e o ESP não aplicam parâmetros obrigatórios nem definições de tipos e encaminham pedidos para a sua API.
O Extensible Service Proxy e o ESP só suportam tipos primitivos em parâmetros de pedidos.
Referências de tipo externo
O Cloud Endpoints não suporta referências a tipos fora do documento OpenAPI. Por exemplo, não pode usar um $ref para um URL externo.
Endereço do anfitrião do serviço de portabilidade personalizado
Não pode usar portas personalizadas no url de um objeto servers.
Limitações de alias do YAML
Um documento OpenAPI pode conter um máximo de 200 nós de alias YAML.
Corpo do pedido não repetitivo
Só pode definir um requestBody por operação e tem de ser de um tipo não repetitivo.