Esta página foi traduzida pela API Cloud Translation.

Limitações das funcionalidades da OpenAPI 3.x

Este documento descreve as limitações de funcionalidades para usar a OpenAPI 3.x com o API Gateway.

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 das novas funcionalidades no OpenAPI 3.x.

Servidores

O OpenAPI 3.x suporta vários objetos server para definir anfitriões e caminhos base. No entanto, o API Gateway baseia-se num único objeto de servidor, identificado pela extensão x-google-endpoint, para configurar o serviço.

Embora possa definir vários servidores, o API Gateway considera apenas o servidor que contém a extensão x-google-endpoint e permite apenas um servidor desse tipo. Para o API Gateway, não é necessário um URL do servidor, pelo que pode não ter servidores definidos ou ter um servidor com a extensão x-google-endpoint.

Por exemplo, as seguintes definições são válidas para o API Gateway:

servers:
  - url: https://example.com
    x-google-endpoint: {}

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com

A seguinte definição é inválida porque contém várias extensões x-google-endpoint:

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com
    x-google-endpoint: {}

A seguinte definição é válida para o API Gateway, mas o API Gateway ignora o objeto do servidor:

servers:
  - url: https://example.com

Servidores em vários ficheiros

Se carregar vários ficheiros OpenAPI e um ficheiro contiver um servidor com a extensão x-google-endpoint, todos os ficheiros também têm de ter um servidor definido com uma extensão x-google-endpoint idêntica e um anfitrião idêntico no URL do servidor. O caminho base pode ser diferente entre ficheiros.

URL relativo

Para o API Gateway, os URLs relativos no objeto servers são tratados como um caminho base por si só, porque não é necessário um nome de anfitrião na especificação. Isto é diferente do comportamento padrão da OpenAPI, que resolve os URLs relativos em relação ao servidor que aloja a definição da OpenAPI. Por exemplo, o API Gateway trata url: /v1 como um caminho base.

Os caminhos base têm de começar por "/". O API Gateway rejeita URLs que não tenham um esquema ou que comecem por "/" para indicar um caminho base.

Extensões não suportadas

O gateway da API não suporta a extensão x-google-allow para a OpenAPI 3.x.

Limites de tamanho de ficheiros

O API Gateway aplica um limite de tamanho total de 10 MB e um limite de contagem de ficheiros de 50 para ficheiros OpenAPI 3.x carregados.

Limitações pré-existentes

Esta secção descreve as limitações transferidas do OpenAPI 2.0 que também se aplicam ao OpenAPI 3.x.

Âmbitos ignorados

Embora o API Gateway aceite documentos OpenAPI com âmbitos definidos num objeto de esquema de segurança, o API Gateway não verifica nem aplica estes âmbitos.

Vários requisitos de segurança

Requisitos da chave da API: o API Gateway não suporta requisitos de segurança alternativos (OR lógico) se um dos esquemas for uma chave da API. No entanto, o API Gateway suporta conjunções (AND lógico), o que lhe permite exigir uma chave da API e um token OAuth2.
Requisitos do OAuth2: o API Gateway suporta requisitos de segurança alternativos (OR lógico) para diferentes esquemas de segurança do OAuth2. O API Gateway não suporta conjunções (AND lógico), a menos que o requisito de segurança adicional seja uma chave da API.
Segurança opcional: pode usar um requisito de segurança vazio (- {}) para tornar a segurança opcional para uma chave da API, mas o API Gateway não suporta esta opção para o OAuth.

Validação da definição de segurança

O API Gateway rejeita uma especificação OpenAPI 3.x que use um requisito de segurança sem uma definição correspondente na secção securityDefinitions.

Criação de modelos de caminhos de URLs

O API Gateway só suporta parâmetros de modelo de caminho de URL que representam segmentos de caminho completos, por exemplo, /items/{itemId}. O API Gateway não suporta nem rejeita parâmetros correspondentes a segmentos parciais, por exemplo, /items/prefix_{id}_suffix.

Parâmetros, esquemas, corpos de pedidos e tipos

O API Gateway aceita documentos OpenAPI com várias definições de parâmetros e tipos (por exemplo, required parâmetros e formatos de matriz), mas não os aplica. O Gateway da API encaminha os pedidos recebidos para a sua API, independentemente destas definições.

O API Gateway apenas suporta tipos primitivos nos parâmetros de pedido.

Referências de tipo externo

O API Gateway não suporta referências a tipos fora do documento OpenAPI facultado. Por exemplo, o Gateway da API não permite e rejeita um $ref que aponte para um URL externo.

Porta personalizada no endereço do anfitrião

O API Gateway não permite portas personalizadas no campo servers.url de um documento OpenAPI.

Limitações de alias do YAML

Um documento OpenAPI enviado para o API Gateway pode ter um máximo de 200 nós de alias YAML.