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 compatíveis, 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 à OpenAPI 3.x.
Servidores
O OpenAPI 3.x é compatível com vários objetos server para definir hosts e caminhos de base. No entanto, o Cloud Endpoints usa apenas um objeto de servidor para configurar o nome do host e o caminho de base, identificados pela extensão x-google-endpoint.
Embora seja possível definir vários servidores na especificação 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, é necessário um nome de host. Portanto, apenas um servidor pode 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 definição de servidor a seguir é 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 definição a seguir 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 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 a 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 basepath no URL do servidor pode ser diferente.
URL relativo
O Cloud Endpoints exige um nome de host e, portanto, não é compatível com URLs relativos.
Extensões não compatíveis
O OpenAPI 3.x não é compatível com a extensão x-google-allow.
Limitações preexistentes
Nesta seção, descrevemos as limitações que existiam no OpenAPI 2.0 e continuam válidas para o OpenAPI 3.x.
Escopos ignorados
Embora seja possível definir escopos em um objeto de esquema de segurança, o ESP ou os 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 aceita requisitos de segurança alternativa (OR lógico) quando um dos esquemas é uma chave de API. O Cloud Endpoints aceita 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 é compatível com requisitos de segurança alternativos (OR lógico) para diferentes esquemas de autenticação OAuth2. O Cloud Endpoints não aceita conjunções (AND lógico), a menos que o requisito de segurança adicional seja uma chave de API.
Requisitos de segurança opcionais: o OpenAPI 3 é compatível com segurança opcional incluindo um requisito vazio (
{}). A chave de API é compatível com isso, mas o OAuth não.
Validação da definição de segurança
Para OpenAPI 3.x, usar um esquema de segurança indefinido resulta em um erro, e o Cloud Endpoints rejeita a especificação. Isso é diferente do OpenAPI 2.0, em que isso só gerava um aviso.
Modelos do caminho do URL
O Cloud Endpoints aceita apenas parâmetros de modelo de caminho de URL que correspondem a segmentos de caminho inteiros (delimitados por /). Ele não aceita parâmetros para segmentos de caminho parciais.
Por exemplo, o Cloud Endpoints é compatível com /items/{itemId}, mas não com /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 é compatível com o 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 restringem parâmetros obrigatórios e definições de tipo, e encaminham solicitações à API.
O Extensible Service Proxy e o ESP só aceitam tipos primitivos em parâmetros de solicitação.
Referências de tipo externo
O Cloud Endpoints não aceita 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 OpenAPI pode conter no máximo 200 nós de alias YAML.
Corpo da solicitação não repetido
Só é possível definir um requestBody por operação, e ele precisa ser de um tipo não repetido.