In diesem Dokument werden die Funktionseinschränkungen für die Verwendung von OpenAPI 3.x mit Endpoints beschrieben.
Weitere Informationen zu unterstützten OpenAPI-Spezifikationsversionen finden Sie unter OpenAPI – Übersicht.
Neue Einschränkungen für OpenAPI 3.x
In diesem Abschnitt werden Einschränkungen für OpenAPI beschrieben, die mit der Unterstützung von OpenAPI 3.x neu eingeführt wurden.
Server
OpenAPI 3.x unterstützt mehrere server-Objekte zum Definieren von Hosts und Basispfaden. Cloud Endpoints verwendet jedoch nur ein einzelnes Serverobjekt zum Konfigurieren des Hostnamens und des Basispfads, das durch die Erweiterung x-google-endpoint identifiziert wird.
Sie können zwar mehrere Server in Ihrer OpenAPI-Spezifikation definieren, Cloud Endpoints verwendet jedoch nur den Server mit der Erweiterung x-google-endpoint. Sie können die Erweiterung x-google-endpoint nur auf einem Server definieren.
Für Cloud Endpoints ist ein Hostname erforderlich. Daher darf nur ein Server die Erweiterung x-google-endpoint haben.
Die folgenden Serverdefinitionen sind beispielsweise für Cloud Endpoints gültig:
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
Die folgende Serverdefinition ist für Endpoints ungültig:
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: {}
Die folgende Definition ist auch für Cloud Endpoints ungültig:
servers:
- url: https://my-api.endpoints.my-project-id.cloud.goog
Server in mehreren Dateien
Wenn Sie mehrere OpenAPI-Dateien hochladen, müssen alle Dateien die Einschränkungen im Abschnitt servers einhalten. Wenn eine Datei einen Server mit der Erweiterung x-google-endpoint enthält, müssen alle Dateien einen Server mit einer Erweiterung x-google-endpoint definieren.
Außerdem müssen alle Server mit der Erweiterung x-google-endpoint einen identischen Host in der Server-URL verwenden und die Konfiguration x-google-endpoint muss in allen Dateien identisch sein. Der Basispfad in der Server-URL kann sich unterscheiden.
Relative URL
Cloud Endpoints erfordert einen Hostnamen und unterstützt daher keine relativen URLs.
Nicht unterstützte Erweiterungen
OpenAPI 3.x unterstützt die Erweiterung x-google-allow nicht.
Vorhandene Einschränkungen
In diesem Abschnitt werden Einschränkungen beschrieben, die in OpenAPI 2.0 vorhanden waren und weiterhin für OpenAPI 3.x gelten.
Ignorierte Bereiche
Obwohl Sie Bereiche in einem Sicherheitsschemaobjekt definieren können, werden sie vom ESP oder von Cloud Endpoints Frameworks nicht geprüft.
Mehrere Sicherheitsanforderungen
Sie können in Ihrem OpenAPI-Dokument mehrere Sicherheitsanforderungen angeben.
Sicherheitsanforderungen mit einem API-Schlüssel: Cloud Endpoints unterstützt keine alternativen Sicherheitsanforderungen (logisches ODER), wenn eines der Schemas ein API-Schlüssel ist. Cloud Endpoints unterstützt Verknüpfungen (logisches UND), sodass Sie sowohl einen API-Schlüssel als auch die OAuth2-Authentifizierung festlegen können.
Sicherheitsanforderungen für OAuth2: Cloud Endpoints unterstützt alternative Sicherheitsanforderungen (logisches ODER) für verschiedene OAuth2-Authentifizierungsschemas. Cloud Endpoints unterstützt keine Verknüpfungen (logisches UND), es sei denn, die zusätzliche Sicherheitsanforderung ist ein API-Schlüssel.
Optionale Sicherheitsanforderungen: OpenAPI 3 unterstützt optionale Sicherheit, indem eine leere Anforderung (
{}) eingefügt wird. API-Schlüssel unterstützen dies, OAuth jedoch nicht.
Validierung der Sicherheitsdefinition
Wenn Sie in OpenAPI 3.x ein nicht definiertes Sicherheitsschema verwenden, führt dies zu einem Fehler und Cloud Endpoints lehnt die Spezifikation ab. Dies ist eine Änderung gegenüber OpenAPI 2.0, wo dies nur eine Warnung erzeugte.
URL-Pfadvorlagen
Cloud Endpoints unterstützt nur URL-Pfadvorlagenparameter, die vollständigen Pfadsegmenten entsprechen (durch / getrennt). Cloud Endpoints unterstützt keine Parameter für Teilpfadsegmente.
Cloud Endpoints unterstützt beispielsweise /items/{itemId}, aber nicht /items/overview.{format}.
Vorgänge für den URL-Root-Pfad /
Das OpenAPI-Dokument akzeptiert zwar Vorgänge für den Root-Pfad /, der Extensible Service Proxy lehnt jedoch Anfragen an den Root-Pfad ab. Diese Einschränkung gilt nicht für ESPv2, das den Root-Pfad unterstützt.
Parameter, Schemas, Anfragetexte und Typen
Der Extensible Service Proxy und ESP ignorieren die meisten Parameter-, Schema-, Anfragetext- und Typdefinitionen. Der Extensible Service Proxy und ESP erzwingen keine erforderlichen Parameter- und Typdefinitionen und leiten Anfragen an Ihre API weiter.
Der Extensible Service Proxy und ESP unterstützen nur primitive Typen in Anfrageparametern.
Verweise auf externe Typen
Cloud Endpoints unterstützt keine Verweise auf Typen außerhalb des OpenAPI-Dokuments. Sie können beispielsweise keinen $ref auf eine externe URL verwenden.
Benutzerdefinierter Port in Diensthostadresse
Sie können in der url eines servers-Objekts keine benutzerdefinierten Ports verwenden.
Einschränkungen für YAML-Aliasse
Ein OpenAPI-Dokument kann maximal 200 YAML-Alias-Knoten enthalten.
Nicht wiederholbarer Anfragetext
Sie können nur einen requestBody pro Vorgang definieren und er muss einen nicht wiederholbaren Typ haben.