In diesem Dokument werden die Einschränkungen bei der Verwendung von OpenAPI 3.x mit Cloud Endpoints beschrieben.
Weitere Informationen zu unterstützten OpenAPI-Spezifikationsversionen finden Sie in der 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 sind.
Server
OpenAPI 3.x unterstützt mehrere server-Objekte zum Definieren von Hosts und Basispfaden. Cloud Endpoints verwendet jedoch nur ein einzelnes Serverobjekt, um den Hostnamen und den Basispfad zu konfigurieren, die durch die Erweiterung x-google-endpoint identifiziert werden.
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 x-google-endpoint-Erweiterung 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 gültig für 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
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 den Einschränkungen im Abschnitt servers entsprechen. Wenn eine Datei einen Server mit der Erweiterung x-google-endpoint enthält, muss in allen Dateien ein Server mit der Erweiterung x-google-endpoint definiert sein.
Außerdem müssen alle Server mit der Erweiterung x-google-endpoint in der Server-URL denselben Host verwenden und die x-google-endpoint-Konfiguration muss in allen Dateien identisch sein. Der Basispfad in der Server-URL kann abweichen.
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.
Bestehende 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 Konjunktionen (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 durch Einbeziehung einer leeren Anforderung (
{}). API-Schlüssel unterstützen dies, OAuth jedoch nicht.
Validierung der Sicherheitsdefinition
Bei OpenAPI 3.x führt die Verwendung eines nicht definierten Sicherheitsschemas zu einem Fehler und Cloud Endpoints lehnt die Spezifikation ab. In OpenAPI 2.0 wurde in diesem Fall nur eine Warnung ausgegeben.
URL-Pfadvorlagen
Cloud Endpoints unterstützt nur URL-Pfadvorlagenparameter, die vollständigen Pfadsegmenten entsprechen (durch / getrennt). Parameter für Teilpfadsegmente werden nicht unterstützt.
Cloud Endpoints unterstützt beispielsweise /items/{itemId}, aber nicht /items/overview.{format}.
Vorgänge für den URL-Root-Pfad /
Obwohl das OpenAPI-Dokument Vorgänge im Root-Pfad / akzeptiert, lehnt der Extensible Service Proxy Anfragen an den Root-Pfad ab. Diese Einschränkung gilt nicht für ESPv2, das den Stammpfad unterstützt.
Parameter, Schemas, Anfragetexte und Typen
Der Extensible Service Proxy (ESP) 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 (ESP) 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 keine $ref zu einer externen URL verwenden.
Benutzerdefinierter Port in Diensthostadresse
Sie können keine benutzerdefinierten Ports im url eines servers-Objekts verwenden.
Einschränkungen bei YAML-Aliasen
Ein OpenAPI-Dokument kann maximal 200 YAML-Alias-Knoten enthalten.
Nicht wiederholter Anfragetext
Sie können nur ein requestBody pro Vorgang definieren und es muss ein nicht wiederholender Typ sein.