Questo documento descrive le limitazioni delle funzionalità per l'utilizzo di OpenAPI 3.x con Endpoints.
Per ulteriori informazioni sulle versioni supportate della specifica OpenAPI, consulta la panoramica di OpenAPI.
Nuovi limiti di OpenAPI 3.x
Questa sezione descrive le limitazioni per OpenAPI che sono nuove con il supporto di OpenAPI 3.x.
Server
OpenAPI 3.x supporta più oggetti server per definire host e percorsi di base. Tuttavia, Cloud Endpoints utilizza un solo oggetto server per configurare il nome host e il percorso di base, identificato dall'estensione x-google-endpoint.
Anche se puoi definire più server nella specifica OpenAPI, Cloud Endpoints utilizza solo il server con l'estensione x-google-endpoint. Puoi definire l'estensione x-google-endpoint su un solo server.
Per Cloud Endpoints, è necessario un nome host, quindi solo un server deve avere l'estensione x-google-endpoint.
Ad esempio, le seguenti definizioni del server sono valide per 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
La seguente definizione del server non è valida per 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: {}
Anche la seguente definizione non è valida per Cloud Endpoints:
servers:
- url: https://my-api.endpoints.my-project-id.cloud.goog
Server in più file
Se carichi più file OpenAPI, tutti i file devono rispettare i limiti della sezione servers. Se un file contiene un server con l'estensione x-google-endpoint, tutti i file devono definire un server con l'estensione x-google-endpoint.
Inoltre, tutti i server con estensione x-google-endpoint devono utilizzare un host identico nell'URL del server e la configurazione x-google-endpoint deve essere identica in tutti i file. Il percorso di base nell'URL del server può variare.
URL relativo
Cloud Endpoints richiede un nome host, pertanto non supporta gli URL relativi.
Estensioni non supportate
OpenAPI 3.x non supporta l'estensione x-google-allow.
Limitazioni preesistenti
Questa sezione descrive le limitazioni esistenti in OpenAPI 2.0 e che continuano ad applicarsi a OpenAPI 3.x.
Ambiti ignorati
Anche se puoi definire gli ambiti in un oggetto schema di sicurezza, ESP o Cloud Endpoints Frameworks non li controllano.
Più requisiti di sicurezza
Puoi specificare più di un requisito di sicurezza nel documento OpenAPI.
Requisiti di sicurezza con una chiave API: Cloud Endpoints non supporta requisiti di sicurezza alternativi (OR logico) quando uno degli schemi è una chiave API. Cloud Endpoints supporta le congiunzioni (AND logico), quindi puoi richiedere sia una chiave API sia l'autenticazione OAuth2.
Requisiti di sicurezza per OAuth2: Cloud Endpoints supporta requisiti di sicurezza alternativi (OR logico) per diversi schemi di autenticazione OAuth2. Cloud Endpoints non supporta le congiunzioni (AND logico) a meno che il requisito di sicurezza aggiuntivo non sia una chiave API.
Requisiti di sicurezza facoltativi: OpenAPI 3 supporta la sicurezza facoltativa includendo un requisito vuoto (
{}). La chiave API lo supporta, ma OAuth no.
Convalida della definizione di sicurezza
Per OpenAPI 3.x, l'utilizzo di uno schema di sicurezza non definito genera un errore e Cloud Endpoints rifiuta la specifica. Si tratta di una modifica rispetto a OpenAPI 2.0, in cui veniva generato solo un avviso.
Modelli di percorso dell'URL
Cloud Endpoints supporta solo i parametri del modello di percorso URL che corrispondono a segmenti di percorso interi (delimitati da /). Cloud Endpoints non supporta i parametri per i segmenti di percorso parziali.
Ad esempio, Cloud Endpoints supporta /items/{itemId}, ma non /items/overview.{format}.
Operazioni sul percorso principale dell'URL /
Sebbene il documento OpenAPI accetti operazioni sul percorso principale /, Extensible Service Proxy rifiuta le richieste al percorso principale. Questa limitazione non si applica a ESPv2, che supporta il percorso principale.
Parametri, schemi, corpi delle richieste e tipi
Extensible Service Proxy e ESP ignorano la maggior parte delle definizioni di parametri, schema, corpo della richiesta e tipo. Extensible Service Proxy e ESP non applicano i parametri e le definizioni di tipo obbligatori e inoltrano le richieste alla tua API.
Extensible Service Proxy ed ESP supportano solo i tipi primitivi nei parametri della richiesta.
Riferimenti a tipi esterni
Cloud Endpoints non supporta i riferimenti a tipi esterni al documento OpenAPI. Ad esempio, non puoi utilizzare un $ref per un URL esterno.
Porta personalizzata nell'indirizzo host del servizio
Non puoi utilizzare porte personalizzate in url di un oggetto servers.
Limitazioni degli alias YAML
Un documento OpenAPI può contenere un massimo di 200 nodi alias YAML.
Corpo della richiesta non ripetuto
Puoi definire un solo requestBody per operazione e deve essere di tipo non ripetitivo.