Questa pagina è stata tradotta dall'API Cloud Translation.

Limitazioni delle funzionalità di OpenAPI 3.x

Questo documento descrive le limitazioni delle funzionalità per l'utilizzo di OpenAPI 3.x con API Gateway.

Per ulteriori informazioni sulle versioni supportate della specifica OpenAPI, consulta la panoramica di OpenAPI.

Nuove limitazioni di OpenAPI 3.x

Questa sezione descrive le limitazioni per le nuove funzionalità di OpenAPI 3.x.

Server

OpenAPI 3.x supporta più oggetti server per definire host e percorsi di base. Tuttavia, API Gateway si basa su un singolo oggetto server, identificato dall'estensione x-google-endpoint, per configurare il servizio.

Sebbene tu possa definire più server, API Gateway prende in considerazione solo il server che contiene l'estensione x-google-endpoint e ne consente uno solo. Per API Gateway, non è necessario un URL del server, quindi puoi non definire alcun server o definire un server con l'estensione x-google-endpoint.

Ad esempio, le seguenti definizioni sono valide per API Gateway:

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

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

La seguente definizione non è valida perché contiene più estensioni x-google-endpoint:

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

La seguente definizione è valida per API Gateway, ma API Gateway ignora l'oggetto server:

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

Server in più file

Se carichi più file OpenAPI e uno contiene un server con l'estensione x-google-endpoint, anche tutti gli altri file devono avere un server definito con un'estensione x-google-endpoint identica e un host identico nell'URL del server. Il percorso di base può variare tra i file.

URL relativo

Per API Gateway, gli URL relativi nell'oggetto servers vengono trattati come un basepath autonomo perché non è richiesto un nome host nella specifica. Questo comportamento è diverso da quello standard di OpenAPI, che risolve gli URL relativi rispetto al server che ospita la definizione OpenAPI. Ad esempio, API Gateway considera url: /v1 come basepath.

I percorsi di base devono iniziare con "/". API Gateway rifiuta gli URL che non hanno uno schema o che iniziano con "/" per indicare un percorso di base.

Estensioni non supportate

API Gateway non supporta l'estensione x-google-allow per OpenAPI 3.x.

Limiti di dimensione dei file

API Gateway applica un limite di dimensioni totali di 10 MB e un limite di conteggio dei file di 50 per i file OpenAPI 3.x caricati.

Limitazioni preesistenti

Questa sezione descrive le limitazioni riportate da OpenAPI 2.0 che si applicano anche a OpenAPI 3.x.

Ambiti ignorati

Sebbene API Gateway accetti documenti OpenAPI con ambiti definiti in un oggetto schema di sicurezza, non li controlla né li applica.

Più requisiti di sicurezza

Requisiti della chiave API: API Gateway non supporta requisiti di sicurezza alternativi (OR logico) se uno degli schemi è una chiave API. Tuttavia, API Gateway supporta le congiunzioni (AND logico), che ti consentono di richiedere sia una chiave API sia un token OAuth2.
Requisiti OAuth2: API Gateway supporta requisiti di sicurezza alternativi (OR logico) per diversi schemi di sicurezza OAuth2. API Gateway non supporta le congiunzioni (AND logico) a meno che il requisito di sicurezza aggiuntivo non sia una chiave API.
Sicurezza facoltativa: puoi utilizzare un requisito di sicurezza vuoto (- {}) per rendere la sicurezza facoltativa per una chiave API, ma API Gateway non lo supporta per OAuth.

Convalida della definizione di sicurezza

API Gateway rifiuterà una specifica OpenAPI 3.x che utilizza un requisito di sicurezza senza una definizione corrispondente nella sezione securityDefinitions.

Modelli di percorso dell'URL

API Gateway supporta solo i parametri del modello di percorso URL che rappresentano interi segmenti di percorso, ad esempio /items/{itemId}. API Gateway non supporta e rifiuta i parametri corrispondenti a segmenti parziali, ad esempio /items/prefix_{id}_suffix.

Parametri, schemi, corpi delle richieste e tipi

API Gateway accetta documenti OpenAPI con varie definizioni di parametri e tipi (ad esempio parametri required e formati di array), ma non le applica. API Gateway inoltra le richieste in entrata alla tua API indipendentemente da queste definizioni.

API Gateway supporta solo i tipi primitivi nei parametri della richiesta.

Riferimenti a tipi esterni

API Gateway non supporta i riferimenti a tipi esterni al documento OpenAPI fornito. Ad esempio, API Gateway non consente e rifiuta un $ref che punta a un URL esterno.

Porta personalizzata nell'indirizzo host

API Gateway non consente porte personalizzate nel campo servers.url di un documento OpenAPI.

Limitazioni degli alias YAML

Un documento OpenAPI inviato ad API Gateway può avere un massimo di 200 nodi alias YAML.