Esta página foi traduzida pela API Cloud Translation.

Limitações de recursos da OpenAPI 3.x

Este documento descreve as limitações de recursos ao usar a OpenAPI 3.x com o gateway de API.

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 dos recursos novos na 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 API Gateway depende de um único objeto de servidor, identificado pela extensão x-google-endpoint, para configurar o serviço.

Embora seja possível definir vários servidores, a API Gateway considera apenas o servidor que contém a extensão x-google-endpoint e permite apenas um servidor desse tipo. Para o gateway de API, não é necessário um URL de servidor. Portanto, você 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 gateway de API:

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

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

A definição a seguir é 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 definição a seguir é válida para o gateway de API, mas ele ignora o objeto do servidor:

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

Servidores em vários arquivos

Se você fizer upload de vários arquivos OpenAPI e um deles tiver um servidor com a extensão x-google-endpoint, todos os arquivos também precisarão ter um servidor definido com uma extensão x-google-endpoint idêntica e um host idêntico no URL do servidor. O caminho base pode ser diferente entre os arquivos.

URL relativo

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

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

Extensões incompatíveis

O gateway de API não é compatível com a extensão x-google-allow para OpenAPI 3.x.

Limites do tamanho do arquivo

O API Gateway aplica um limite de tamanho total de 10 MB e um limite de contagem de arquivos de 50 para arquivos OpenAPI 3.x enviados por upload.

Limitações preexistentes

Esta seção descreve as limitações da OpenAPI 2.0 que também se aplicam à OpenAPI 3.x.

Escopos ignorados

Embora o gateway de API aceite documentos OpenAPI com escopos definidos em um objeto de esquema de segurança, ele não verifica nem aplica esses escopos.

Vários requisitos de segurança

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

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

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

Modelos do caminho do URL

A API Gateway aceita apenas parâmetros de modelo de caminho de URL que representam segmentos de caminho inteiros, por exemplo, /items/{itemId}. O gateway de API não aceita parâmetros correspondentes a segmentos parciais, por exemplo, /items/prefix_{id}_suffix.

Parâmetros, esquemas, corpos de solicitação e tipos

O API Gateway aceita documentos OpenAPI com várias definições de parâmetro e tipo (por exemplo, parâmetros required e formatos de matriz), mas não os aplica. O gateway de API encaminha as solicitações recebidas para sua API, independentemente dessas definições.

O gateway de API aceita apenas tipos primitivos em parâmetros de solicitação.

Referências de tipo externo

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

Porta personalizada no endereço do host

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

Limitações de alias do YAML

Um documento da OpenAPI enviado ao API Gateway pode ter no máximo 200 nós de alias YAML.