Attualmente, Cloud Endpoints accetta solo la versione 2 della specifica OpenAPI.
Le sezioni seguenti descrivono le limitazioni delle funzionalità OpenAPI sugli endpoint.
Ambiti ignorati
Sebbene Endpoints accetti documenti OpenAPI con ambiti definiti in un oggetto dello schema di sicurezza, quando viene inviata una richiesta all'API, né l'Extensible Service Proxy (ESP) né i framework Cloud Endpoints Frameworks controllano gli ambiti definiti.
Più requisiti di sicurezza
Puoi specificare più di un requisito di sicurezza nel documento OpenAPI. Questa sezione descrive gli schemi di sicurezza supportati da ESP.
Requisiti di sicurezza contenenti una chiave API
ESP non supporta i requisiti di sicurezza alternativa (OR logico) quando uno degli schemi di sicurezza è una chiave API. Ad esempio, ESP non supporta il seguente elenco di requisiti di sicurezza:
security:
- petstore_auth: []
- api_key: []
Questa definizione richiede che un'operazione accetti richieste che seguono i requisiti petstore_auth o i requisiti api_key.
Tuttavia, tieni presente che ESP supporta le congiunzioni dei requisiti di sicurezza (AND logico), quindi puoi richiedere sia una chiave API sia l'autenticazione OAuth2. Ad esempio, è supportato il seguente elenco di requisiti di sicurezza:
security:
- petstore_auth: []
api_key: []
Questa definizione richiede che un'operazione accetti richieste che seguono contemporaneamente
i requisiti petstore_auth e i requisiti api_key.
Requisiti di sicurezza per OAuth2
ESP supporta i requisiti di sicurezza alternativa (OR logico) per la sicurezza, ma solo per gli schemi di sicurezza dell'autenticazione OAuth2. Ad esempio, è supportato il seguente elenco di requisiti di sicurezza:
security:
- firebase1: []
- firebase2: []
Convalida delle definizioni di sicurezza
L'ESP non convalida la presenza di tutti i requisiti di sicurezza (a livello di API o di metodo) anche nella sezione securityDefinitions. Di conseguenza, se la specifica API utilizza uno schema di sicurezza non definito, le richieste non autenticate possono arrivare attraverso l'API, al livello in cui è configurato il token di sicurezza non definito. Assicurati che tutti i token di sicurezza utilizzati dalla tua API e dai relativi metodi siano definiti nelle definizioni di sicurezza nel documento OpenAPI.
Modelli del percorso dell'URL
Gli endpoint supportano solo i parametri dei modelli di percorso dell'URL che corrispondono a segmenti interi del percorso (delimitati da barre /). I parametri dei modelli di percorso dell'URL che corrispondono a segmenti parziali del percorso non sono supportati.
Ad esempio, i seguenti modelli di percorso dell'URL sono supportati:
/items/{itemId}/items/{itemId}/subitems
I seguenti modelli di percorso dell'URL non sono supportati e verranno rifiutati:
/items/overview.{format}/items/prefix_{id}_suffix
Operazioni sul percorso principale dell'URL /
Endpoints accetta documenti OpenAPI che includono operazioni nel percorso principale /. Tuttavia, le richieste nel percorso principale vengono rifiutate da
ESP. Tieni presente che questa limitazione è solo per ESP,
ESPv2 supporta il percorso root /.
Ad esempio, il seguente snippet di documento OpenAPI è accettato:
paths:
/:
post:
operationId: "root"
responses:
200:
description: "Success"
schema:
type: string
Tuttavia, le successive richieste per POST / vengono rifiutate con il seguente errore:
{
"code": 5,
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"detail": "service_control",
"stackEntries": []
}
],
"message": "Method does not exist."
}
Caricamento file
Gli endpoint non accettano type: file per i parametri di caricamento file, è necessario utilizzare type: string.
Ad esempio, il seguente snippet type: file non è consentito:
paths:
/upload:
post:
summary: Uploads a file.
consumes:
- multipart/form-data
parameters:
- in: formData
name: upfile
type: file
description: The file to upload.
Invece con type: string è consentito:
paths:
/upload:
post:
summary: Uploads a file.
consumes:
- multipart/form-data
parameters:
- in: formData
name: upfile
type: string
description: The file to upload.
Parametri, schemi e tipi
ESP ignora la maggior parte delle definizioni di parametri e tipi.
Endpoints accetta documenti OpenAPI che includono le definizioni di parametri e tipi richiesti, ma ESP non applica queste definizioni e inoltra le richieste in entrata alla tua API. Di seguito è riportato un elenco parziale che fornisce esempi delle definizioni che ESP non applica:
- Parametri dei dati dei moduli, ad esempio:
parameters: - name: avatar in: formData description: "The avatar of the user" type: string
- Parametri obbligatori, ad esempio:
parameters: - name: message in: query description: "Message to send" required: true type: string
- Formati di raccolta di array, ad esempio:
parameters: - name: items in: query description: "List of item IDs" required: true type: array items: type: string collectionFormat: tsv - Composizione del tipo, ad esempio:
definitions: base: properties: message: type: string extended: description: "Extends the base type" allOf: - $ref: "#/definitions/base" - type: object properties: extension: type: string - Oggetti di risposta diversi per codice di stato, ad esempio:
responses: 200: description: "Echo" schema: $ref: "#/definitions/EchoResponse" 400: description: "Error" schema: type: string
Riferimenti a tipi esterni
Gli endpoint non supportano i riferimenti a tipi esterni a un documento OpenAPI. Ad esempio, Endpoints rifiuta i documenti OpenAPI che includono:
parameters:
- name: user
description: User details
in: body
schema:
$ref: "https://example.com/mytype.json"
Porta personalizzata nell'indirizzo host del servizio
Gli endpoint non consentono l'utilizzo di porte personalizzate nel campo host di un documento OpenAPI. Ad esempio, Endpoints rifiuta i documenti OpenAPI come:
swagger: 2.0
host: example.com:8080
schemes:
- http
Limitazioni degli alias YAML
Gli endpoint possono supportare fino a 200 nodi alias YAML in un documento OpenAPI. Se in un documento OpenAPI sono presenti più di 200 alias YAML, ti consigliamo di de-riferire gli alias ove possibile per rispettare questo limite.
Bug noti
Documenti OpenAPI rifiutati
Quando esegui il deployment del tuo documento OpenAPI utilizzando gcloud endpoints services deploy, gli endpoint rifiutano i documenti OpenAPI che includono:
- Parametri del corpo di array, ad esempio:
parameters: - name: message description: "Message to echo" in: body schema: type: array items: type: string - Percorsi con barre finali, ad esempio:
paths: "/echo/": post: description: "Echo back a given message."Per risolvere il problema, rimuovi la barra finale da
/echo/:paths: "/echo": post: description: "Echo back a given message."
Limitazioni della definizione delle chiavi API
Quando specifichi una chiave API nell'oggetto delle definizioni di sicurezza del documento OpenAPI, Endpoints richiede uno dei seguenti schemi:
nameèkeyeinèquerynameèapi_keyeinèquerynameèx-api-keyeinèheader
Ad esempio:
"securityDefinitions": {
"api_key_0": {
"type": "apiKey",
"name": "key",
"in": "query"
},
"api_key_1": {
"type": "apiKey",
"name": "api_key",
"in": "query"
}
"api_key_2": {
"type": "apiKey",
"name": "x-api-key",
"in": "header"
},
}
Quando esegui il deployment di un documento OpenAPI con altri tipi di definizioni di sicurezza della chiave API, gli endpoint potrebbero accettarli e restituire un avviso. Tuttavia, le definizioni di sicurezza della chiave API vengono ignorate nelle richieste in entrata.
Il portale Cloud Endpoints non esegue il rendering dei tipi di composizione
Sebbene Endpoints accetti documenti OpenAPI con tipi di composizione, ovvero tipi con allOf nella definizione, il portale endpoint non genera documentazione per i tipi di composizione.