Einschränkungen der OpenAPI 3.x-Funktionen

In diesem Dokument werden die Einschränkungen bei der Verwendung von OpenAPI 3.x mit API Gateway 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 Funktionen beschrieben, die in OpenAPI 3.x neu sind.

Server

OpenAPI 3.x unterstützt mehrere server-Objekte zum Definieren von Hosts und Basispfaden. API Gateway verwendet jedoch ein einzelnes Serverobjekt, das durch die Erweiterung x-google-endpoint identifiziert wird, um den Dienst zu konfigurieren.

Sie können zwar mehrere Server definieren, API Gateway berücksichtigt jedoch nur den Server, der die Erweiterung x-google-endpoint enthält, und lässt nur einen solchen Server zu. Für API Gateway ist keine Server-URL erforderlich. Sie können also entweder keine Server oder einen Server mit der Erweiterung x-google-endpoint definieren.

Die folgenden Definitionen sind beispielsweise gültig für API Gateway:

servers:
  - url: https://example.com
    x-google-endpoint: {}

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com

Die folgende Definition ist ungültig, da sie mehrere x-google-endpoint-Erweiterungen enthält:

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com
    x-google-endpoint: {}

Die folgende Definition ist für API Gateway gültig, aber API Gateway ignoriert das Serverobjekt:

servers:
  - url: https://example.com

Server in mehreren Dateien

Wenn Sie mehrere OpenAPI-Dateien hochladen und eine Datei einen Server mit der Erweiterung x-google-endpoint enthält, müssen alle Dateien auch einen Server mit einer identischen x-google-endpoint-Erweiterung und einem identischen Host in der Server-URL enthalten. Der Basispfad kann sich je nach Datei unterscheiden.

Relative URL

Bei API Gateway werden relative URLs im servers-Objekt als eigener Basispfad behandelt, da in der Spezifikation kein Hostname erforderlich ist. Das unterscheidet sich vom Standardverhalten von OpenAPI, bei dem relative URLs in Bezug auf den Server aufgelöst werden, auf dem die OpenAPI-Definition gehostet wird. API Gateway behandelt beispielsweise url: /v1 als Basispfad.

Basispfade müssen mit „/“ beginnen. API Gateway lehnt URLs ab, die kein Schema haben oder mit „/“ beginnen, um einen Basispfad anzugeben.

Nicht unterstützte Erweiterungen

API Gateway unterstützt die Erweiterung x-google-allow für OpenAPI 3.x nicht.

Maximale Dateigrößen

API Gateway erzwingt eine Gesamtgrößenbeschränkung von 10 MB und eine Beschränkung der Anzahl der Dateien von 50 für hochgeladene OpenAPI 3.x-Dateien.

Bestehende Einschränkungen

In diesem Abschnitt werden Einschränkungen aus OpenAPI 2.0 beschrieben, die auch für OpenAPI 3.x gelten.

Ignorierte Bereiche

Obwohl API Gateway OpenAPI-Dokumente mit Bereichen akzeptiert, die in einem Sicherheitsschemaobjekt definiert sind, werden diese Bereiche von API Gateway nicht geprüft oder erzwungen.

Mehrere Sicherheitsanforderungen

• Anforderungen an API-Schlüssel: API Gateway unterstützt keine alternativen Sicherheitsanforderungen (logisches ODER), wenn eines der Schemas ein API-Schlüssel ist. API Gateway unterstützt jedoch Konjunktionen (logisches UND), sodass Sie sowohl einen API-Schlüssel als auch ein OAuth2-Token festlegen können.
• OAuth2-Anforderungen: API Gateway unterstützt alternative Sicherheitsanforderungen (logisches ODER) für verschiedene OAuth2-Sicherheitsschemas. API Gateway unterstützt keine Konjunktionen (logisches UND), es sei denn, die zusätzliche Sicherheitsanforderung ist ein API-Schlüssel.
• Optionale Sicherheit: Sie können eine leere Sicherheitsanforderung (- {}) verwenden, um die Sicherheit für einen API-Schlüssel optional zu machen. API Gateway unterstützt dies jedoch nicht für OAuth.

Validierung der Sicherheitsdefinition

API Gateway lehnt eine OpenAPI 3.x-Spezifikation ab, in der eine Sicherheitsanforderung ohne entsprechende Definition im Abschnitt securityDefinitions verwendet wird.

URL-Pfadvorlagen

API Gateway unterstützt nur URL-Pfadvorlagenparameter, die vollständige Pfadsegmente darstellen, z. B. /items/{itemId}. API Gateway unterstützt keine Parameter, die sich auf Teilsegmente beziehen, z. B. /items/prefix_{id}_suffix, und lehnt sie ab.

Parameter, Schemas, Anfragetexte und Typen

API Gateway akzeptiert OpenAPI-Dokumente mit verschiedenen Parameter- und Typdefinitionen (z. B. required-Parameter und Array-Formate), erzwingt sie jedoch nicht. API Gateway leitet eingehende Anfragen unabhängig von diesen Definitionen an Ihre API weiter.

API Gateway unterstützt nur primitive Typen in Anfrageparametern.

Verweise auf externe Typen

API Gateway unterstützt keine Verweise auf Typen außerhalb des bereitgestellten OpenAPI-Dokuments. API Gateway lässt beispielsweise keine $ref zu, die auf eine externe URL verweist, und lehnt sie ab.

Benutzerdefinierter Port in Hostadresse

API Gateway lässt keine benutzerdefinierten Ports im Feld servers.url eines OpenAPI-Dokuments zu.

Einschränkungen bei YAML-Aliasen

Ein an API Gateway gesendetes OpenAPI-Dokument kann maximal 200 YAML-Alias-Knoten haben.