Attualmente, Cloud Endpoints accetta solo la versione 2 della specifica OpenAPI.
Le sezioni seguenti descrivono i limiti delle funzioni OpenAPI in Cloud Endpoints.
Requisiti di sicurezza alternativi
Cloud Endpoints non supporta i requisiti di sicurezza alternativi (OR logico). Ad esempio, il seguente elenco di requisiti di sicurezza non è supportato:
security:
- petstore_auth: [...]
- api_key: []
La definizione precedente richiede che un'operazione accetti richieste che seguono i requisiti
petstore_auth
o i requisiti api_key
.
Tuttavia, tieni presente che Cloud Endpoints supporta la combinazione dei requisiti di sicurezza (AND logico). Ad esempio, il seguente elenco di requisiti di sicurezza è supportato:
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
.
Modelli di percorso dell'URL
Cloud Endpoints supporta 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 "/"
Cloud Endpoints accetta documenti OpenAPI che includono operazioni sul percorso principale "/
". Tuttavia, le richieste sul percorso principale vengono rifiutate dal proxy ESP (Extensible Service Proxy).
Ad esempio, il seguente snippet di documento OpenAPI è accettato:
paths:
/:
post:
operationId: "root"
responses:
200:
description: "Success"
schema:
type: string
Le successive richieste di POST /
, invece, 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."
}
Parametri, schemi e tipi
Cloud Endpoints ignora la maggior parte delle definizioni di parametri e tipi.
In particolare, Cloud Endpoints accetta documenti OpenAPI che includono definizioni di parametri e tipi obbligatori, ma tali definizioni non vengono applicate nelle richieste in entrata. Di seguito è riportato un elenco parziale con esempi delle definizioni che Cloud Endpoints accetta ma 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
Cloud Endpoints non supporta i riferimenti a tipi all'esterno di un documento OpenAPI. Ad esempio, Cloud Endpoints rifiuta i documenti OpenAPI che includono:
parameters:
- name: user
description: User details
in: body
schema:
$ref: "https://example.com/mytype.json"
Bug noti
Documenti OpenAPI rifiutati
Quando distribuisci documenti OpenApi tramite gcloud endpoints services deploy
, Cloud Endpoints rifiuta 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
Limitazioni della chiave API
Quando specifichi una chiave API nell'oggetto delle definizioni di sicurezza del tuo documento OpenAPI, Cloud Endpoints richiede quanto segue:
- Il campo
name
deve esserekey
- Il campo
in
deve esserequery
Ad esempio:
"securityDefinitions": {
"api_key": {
"type": "apiKey",
"name": "key",
"in": "query"
}
Quando distribuisci un documento OpenAPI con altri tipi di definizioni di sicurezza della chiave API, Cloud Endpoints potrebbe accettarle e generare un avviso. Tuttavia, le definizioni di sicurezza della chiave API vengono ignorate nelle richieste in entrata.