Cloud Endpoints akzeptiert nur Version 2 der OpenAPI-Spezifikation.
In den folgenden Abschnitten werden die Einschränkungen der OpenAPI-Funktionen auf Cloud Endpoints beschrieben.
Ignorierte Bereiche
Cloud Endpoints akzeptiert zwar OpenAPI-Dokumente, die Bereiche in einem Sicherheitsschemaobjekt definiert ist, wird beim Senden einer Anfrage an Ihre API weder Extensible Service Proxy (ESP), Extensible Service Proxy V2 (ESPv2) oder Cloud Endpoints Frameworks überprüfen Sie die definierten Bereichen.
Mehrere Sicherheitsanforderungen
Sie können in Ihrem OpenAPI-Dokument mehrere Sicherheitsanforderungen angeben. In diesem Abschnitt werden die Sicherheitsschemas beschrieben, die von ESP und ESPv2 unterstützt werden.
Sicherheitsanforderungen, die einen API-Schlüssel enthalten
ESP und ESPv2 unterstützen keine alternativen Sicherheitsmaßnahmen (logisches ODER) wenn eines der Sicherheitsschemas ein API-Schlüssel ist. Beispiel: ESP und ESPv2 unterstützen die folgende Liste von Sicherheitsanforderungen nicht:
security:
- petstore_auth: []
- api_key: []
Diese Definition erfordert, dass ein Vorgang Anfragen akzeptiert, die den petstore_auth- oder den api_key-Anforderungen entsprechen.
Beachten Sie jedoch, dass ESP und ESPv2 miteinander verknüpfte Sicherheitsanforderungen (logisches UND) unterstützen, sodass Sie sowohl einen API-Schlüssel als auch die OAuth2-Authentifizierung festlegen können. Die folgende Liste von Sicherheitsanforderungen wird beispielsweise unterstützt:
security:
- petstore_auth: []
api_key: []
Diese Definition erfordert einen Vorgang, um Anfragen zu akzeptieren, die gleichzeitig den Anforderungen von petstore_auth und api_key entsprechen.
Sicherheitsanforderungen für OAuth2
ESP und ESPv2 unterstützen alternative Sicherheitslösungen (logisches ODER) für die OAuth2-Authentifizierung. Die folgende Liste von Sicherheitsanforderungen wird beispielsweise unterstützt:
security:
- firebase1: []
- firebase2: []
Validierung der Sicherheitsdefinition
ESP und ESPv2 prüfen nicht, ob alle Sicherheitsanforderungen (entweder auf API-Ebene oder Methodenebene) auch im Abschnitt securityDefinitions vorhanden sind. Wenn die API-Spezifikation also ein nicht definiertes Sicherheitsschema verwendet, können nicht authentifizierte Anfragen über die API auf der Ebene gesendet werden, auf der der nicht definierte Sicherheitsschlüssel konfiguriert ist. Achten Sie darauf, dass alle Sicherheitsschlüssel, die von Ihrer API und ihren Methoden verwendet werden, in den Sicherheitsdefinitionen in Ihrem OpenAPI-Dokument definiert sind.
URL-Pfadvorlagen
Endpoints unterstützt nur URL-Pfadvorlagenparameter, die vollständigen Pfadsegmenten entsprechen (durch Schrägstriche / getrennt). URL-Pfadvorlagenparameter, die Teilpfadsegmenten entsprechen, werden nicht unterstützt.
Die folgenden URL-Pfadvorlagen werden beispielsweise unterstützt:
/items/{itemId}/items/{itemId}/subitems
Die folgenden URL-Pfadvorlagen werden nicht unterstützt und abgelehnt:
/items/overview.{format}/items/prefix_{id}_suffix
Vorgänge für den URL-Root-Pfad /
Cloud Endpoints akzeptiert OpenAPI-Dokumente, die Vorgänge im Root-Pfad // beinhalten. Anfragen für den Root-Pfad werden jedoch vom ESP abgelehnt. Hinweis: Diese Einschränkung gilt nur für ESP. ESPv2 unterstützt den Stammpfad /.
Das folgende OpenAPI-Dokument-Snippet wird beispielsweise akzeptiert:
paths:
/:
post:
operationId: "root"
responses:
200:
description: "Success"
schema:
type: string
Nachfolgende Anfragen für POST / werden jedoch mit dem folgenden Fehler abgelehnt:
{
"code": 5,
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"detail": "service_control",
"stackEntries": []
}
],
"message": "Method does not exist."
}
Dateien hochladen
Für Endpunkte wird der Parameter type: file für den Dateiupload nicht akzeptiert. Stattdessen sollte type: string verwendet werden.
Das folgende type: file-Snippet ist beispielsweise nicht zulässig:
paths:
/upload:
post:
summary: Uploads a file.
consumes:
- multipart/form-data
parameters:
- in: formData
name: upfile
type: file
description: The file to upload.
Folgendes ist mit type: string zulässig:
paths:
/upload:
post:
summary: Uploads a file.
consumes:
- multipart/form-data
parameters:
- in: formData
name: upfile
type: string
description: The file to upload.
Parameter, Schemas und Typen
ESP und ESPv2 ignorieren die meisten Parameter- und Typdefinitionen.
ESP und ESPv2 akzeptieren OpenAPI-Dokumente, die erforderliche Parameter- und Typdefinitionen enthalten. Diese Definitionen werden jedoch nicht erzwungen und eingehende Anfragen werden an Ihre API weitergeleitet. Im Folgenden finden Sie eine unvollständige Liste mit Beispielen für Definitionen, die ESP und ESPv2 nicht erzwingen.
- Formulardatenparameter:
parameters: - name: avatar in: formData description: "The avatar of the user" type: string
- Erforderliche Parameter wie:
parameters: - name: message in: query description: "Message to send" required: true type: string
- Arraysammlungsformate wie:
parameters: - name: items in: query description: "List of item IDs" required: true type: array items: type: string collectionFormat: tsv - Typerstellung wie:
definitions: base: properties: message: type: string extended: description: "Extends the base type" allOf: - $ref: "#/definitions/base" - type: object properties: extension: type: string - Verschiedene Antwortobjekte nach Statuscode wie:
responses: 200: description: "Echo" schema: $ref: "#/definitions/EchoResponse" 400: description: "Error" schema: type: string
Verweise auf externe Typen
Cloud Endpoints unterstützt keine Verweise auf Typen außerhalb eines OpenAPI-Dokuments. Cloud Endpoints lehnt beispielsweise OpenAPI-Dokumente ab, die Folgendes enthalten:
parameters:
- name: user
description: User details
in: body
schema:
$ref: "https://example.com/mytype.json"
Benutzerdefinierter Port in Diensthostadresse
Endpoints lässt keine benutzerdefinierten Ports im Feld host eines OpenAPI-Dokuments zu. Cloud Endpoints lehnt beispielsweise folgende OpenAPI-Dokumente ab:
swagger: 2.0
host: example.com:8080
schemes:
- http
Einschränkungen bei YAML-Aliassen
Endpoints unterstützt bis zu 200 YAML-Aliasknoten in einem OpenAPI-Dokument. Wenn es mehr als 200 YAML-Aliasse in einer OpenAPI gibt empfehlen wir, Aliasse nach Möglichkeit zu dereferenzieren, um die Limit
Bekannte Programmfehler
OpenAPI-Dokumente abgelehnt
Wenn Sie ein OpenAPI-Dokument mit gcloud endpoints services deploy bereitstellen, lehnt Endpoints OpenAPI-Dokumente ab, die Folgendes enthalten:
- Arraytextparameter wie:
parameters: - name: message description: "Message to echo" in: body schema: type: array items: type: string - Pfade mit abschließenden Schrägstrichen, zum Beispiel:
paths: "/echo/": post: description: "Echo back a given message."Entfernen Sie den abschließenden Schrägstrich aus
/echo/, um dieses Problem zu beheben:paths: "/echo": post: description: "Echo back a given message."
Einschränkungen bei der API-Schlüsseldefinition
Bei der Angabe eines API-Schlüssels im Objekt für Sicherheitsdefinitionen in Ihrem OpenAPI-Dokument erfordert Endpoints eines der folgenden Schemas:
- Der
nameistkeyund derinistquery - Der
nameistapi_keyund derinistquery - Der
nameistx-api-keyund derinistheader
Beispiel:
"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"
},
}
Wenn Sie ein OpenAPI-Dokument mit anderen Arten von Sicherheitsdefinitionen für API-Schlüssel bereitstellen, akzeptiert Cloud Endpoints diese möglicherweise und gibt eine Warnung aus. Die API-Schlüssel-Sicherheitsdefinitionen werden jedoch in eingehenden Anfragen ignoriert.