Gateway für die Verwendung von OpenAPI 3.x ändern

Auf dieser Seite wird beschrieben, wie Sie ein vorhandenes API-Gateway so ändern, dass für die API-Konfiguration eine OpenAPI 3.x-Spezifikation verwendet wird.

Hinweise

  • Prüfen Sie, ob Sie eine API Gateway-Instanz haben, die mit einer OpenAPI 2.0-Spezifikation konfiguriert ist.
  • Installieren Sie die gcloud-Befehlszeile. Weitere Informationen finden Sie unter Google Cloud CLI installieren.

API-Konfiguration für die Verwendung von OpenAPI 3.x ändern

So ändern Sie eine vorhandene OpenAPI 2.0-API Gateway-Konfiguration, damit OpenAPI 3.x verwendet wird:

Aktuelle API-Konfiguration abrufen

Suchen Sie nach der API-Konfiguration, die mit Ihrem Gateway verknüpft ist.

  1. Beschreiben Sie Ihre API Gateway-Instanz:

    gcloud api-gateway gateways describe GATEWAY_ID --project=PROJECT_ID --location=GATEWAY_LOCATION

    Ersetzen Sie Folgendes:

    • GATEWAY_ID: Die ID Ihres Gateways.
    • PROJECT_ID: Ihre Google Cloud Projekt-ID
    • GATEWAY_LOCATION: Der Standort Ihres Gateways.

    In der Ausgabe wird der Pfad apiConfig angezeigt, z. B.:

    apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-gateway-config
createTime: '2025-03-25T02:49:58.641650649Z'
defaultHostname: my-gateway-a1b2c3d4.uc.gateway.dev
displayName: My gateway
name: projects/my-project/locations/us-west1/gateways/my-new-gateway
state: ACTIVE
updateTime: '2025-03-25T02:51:52.674308428Z'

OpenAPI-Dokument abrufen

So rufen Sie das OpenAPI-Dokument für die von Ihnen identifizierte API-Konfiguration ab:

  1. Beschreiben Sie die API-Konfiguration:

    gcloud api-gateway api-configs describe CONFIG_ID --api=API_ID --project=PROJECT_ID --view=FULL

    Ersetzen Sie Folgendes:

    • CONFIG_ID: Die ID Ihrer API-Konfiguration.
    • API_ID: Die ID Ihrer API.
    • PROJECT_ID: Ihre Google Cloud Projekt-ID

    Die Ausgabe enthält den Abschnitt openapiDocuments mit dem base64-codierten Inhalt Ihres OpenAPI-Dokuments:

    createTime: '2024-02-16T21:11:36.293169474Z'
displayName: my-api-config
gatewayServiceAccount: projects/-/serviceAccounts/api-gateway-sa@my-sandbox.iam.gserviceaccount.com
name: projects/my-project-id/locations/global/apis/my-api/configs/my-gateway-config
openapiDocuments:
-   document:
    contents: IyBvc...
    path: apigateway-config.yaml
serviceConfigId: my-api-config-0a1fjkfeb7t8z
state: ACTIVE
updateTime: '2024-02-16T21:13:45.626771120Z'

OpenAPI-Dokument decodieren

So decodieren Sie den base64-codierten Inhalt des OpenAPI-Dokuments:

  1. Decodieren Sie den Wert contents:

    echo 'IyBvc...' | base64 -d

    Ersetzen Sie IyBvc... durch den tatsächlichen contents-Wert aus dem vorherigen Schritt.

    In der Ausgabe wird Ihr OpenAPI 2.0-Dokument angezeigt, z. B.:

    swagger: '2.0'
info:
  title: API_ID
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0

OpenAPI-Dokument in OpenAPI 3.x konvertieren

Sie können ein Tool verwenden, um Ihr OpenAPI 2.0-Dokument in OpenAPI 3.x zu konvertieren. Swagger Editor bietet beispielsweise ein Konvertierungstool.

Nach der ersten Konvertierung in OpenAPI 3.x müssen Sie alle zusätzlichen Änderungen manuell auf das Dokument anwenden, um es an OpenAPI 3.x anzupassen und die Kompatibilität mit API Gateway-Erweiterungen und ‑Funktionen zu gewährleisten. Weitere Informationen zu unterstützten OpenAPI 3.x-Erweiterungen in API Gateway finden Sie unter OpenAPI 3.x-Erweiterungen in API Gateway.

In der folgenden Tabelle werden die erforderlichen Änderungen beschrieben:

Funktion OpenAPI 2.0 OpenAPI 3.x Beschreibung der Änderung
API-Schlüssel securityDefinitions securitySchemes API-Schlüssel nutzen die sofort einsatzbereite Unterstützung für OpenAPI-API-Schlüssel. Konvertierungstools erledigen dies in der Regel automatisch. Es sind keine manuellen Änderungen erforderlich.
JWT-Authentifizierung x-google-audiences usw. x-google-auth In OpenAPI 2.0-Erweiterungen definieren Sie die OAuth-Konfiguration mit einzelnen Erweiterungen für eine securityDefinition-Instanz. Mit Conversion-Tools wird die Sicherheitskonfigurationsinstanz in #/components/securitySchemes konvertiert, die Erweiterungen bleiben erhalten. Ändern Sie diese Erweiterungen manuell, sodass sie untergeordnete Elemente von x-google-auth sind, und entfernen Sie das Präfix x-google-. Die Werte bleiben gleich.
Kontingent x-google-management, x-google-quota x-google-api-management, x-google-quota In OpenAPI 2.0-Erweiterungen definieren Sie Messwerte und Kontingente in x-google-management und hängen sie mit x-google-quota an. Bei der Konvertierung bleiben diese Erweiterungen erhalten. Messwerte und Kontingentkonfiguration manuell von x-google-management nach x-google-api-management verschieben. Ändern Sie die Konfiguration so, dass YAML-Schlüssel verwendet werden, und entfernen Sie valueType, metricKind und unit. Entfernen Sie metricCosts aus Instanzen von x-google-quota.
Back-Ends x-google-backend x-google-api-management, x-google-backend In OpenAPI 2.0-Erweiterungen definieren Sie Back-Ends in x-google-backend. Die Konfiguration gilt dort, wo sie definiert ist. In OpenAPI 3.x-Erweiterungen definieren Sie das Backend in x-google-api-management und wenden es dann mit x-google-backend an. Bei Conversion-Tools bleibt diese Erweiterung erhalten. Verschieben Sie die Konfiguration manuell nach x-google-api-management. Ändern Sie Instanzen von x-google-backend, damit sie auf diese Konfiguration verweisen.
Endpunkte x-google-endpoints x-google-endpoint, servers In OpenAPI 2.0-Erweiterungen definieren Sie die Endpoints-Konfiguration in x-google-endpoints. In OpenAPI 3.x-Erweiterungen verwenden Sie x-google-endpoint, aber es ist eine Erweiterung von servers und nicht auf der Stammebene. Conversion-Tools lassen diese Erweiterung unverändert. Verschieben Sie dies manuell in servers und entfernen Sie das Feld name. Beispiel: 
# OpenAPI 2.0
x-google-endpoints:
- name: "my-api.apigateway.my-project.cloud.goog"
  allowCors: True
# OpenAPI 3.0.x
servers:
- url: https://my-api.apigateway.my-project.cloud.goog/
  x-google-endpoint:
    allowCors: True
API-Namen x-google-api-name x-google-api-management In OpenAPI 2.0-Erweiterungen definieren Sie API-Namen in x-google-api-name. In OpenAPI 3.x-Erweiterungen verwenden Sie das Feld apiName in x-google-api-management. Verschieben Sie diese Konfiguration manuell nach x-google-api-management.
Jeden Traffic zulassen x-google-allow NICHT UNTERSTÜTZT Entfernen Sie dies aus dem OpenAPI-Dokument. API Gateway unterstützt dies in OpenAPI 3.x nicht.

Neue API-Konfiguration erstellen

Erstellen Sie eine neue API-Konfiguration mit Ihrem geänderten OpenAPI 3.x-Dokument.

  1. Erstellen Sie die API-Konfiguration:

    gcloud api-gateway api-configs create NEW_CONFIG_ID --api=API_ID --project=PROJECT_ID --openapi-spec=NEW_API_DEFINITION

    Ersetzen Sie Folgendes:

    • NEW_CONFIG_ID: Eine neue ID für Ihre API-Konfiguration.
    • API_ID: Die ID Ihrer API.
    • PROJECT_ID: Ihre Google Cloud Projekt-ID
    • NEW_API_DEFINITION: Der Pfad zu Ihrer OpenAPI 3.x-Spezifikationsdatei.

Gateway aktualisieren

Aktualisieren Sie Ihre Gateway-Instanz, damit sie auf die neue API-Konfiguration aus Ihrem geänderten OpenAPI 3.x-Dokument verweist.

  1. Aktualisieren Sie das Gateway:

    gcloud api-gateway gateways update GATEWAY_ID --api-config=API_CONFIG --project=PROJECT_ID --location=GATEWAY_LOCATION

    Ersetzen Sie Folgendes:

    • GATEWAY_ID: Die ID Ihres Gateways.
    • API_CONFIG: Der vollständige Ressourcenpfad Ihrer neuen API-Konfiguration, z. B.:projects/PROJECT_ID/locations/global/apis/API_ID/configs/NEW_CONFIG_ID
    • PROJECT_ID: Ihre Google Cloud Projekt-ID
    • GATEWAY_LOCATION: Der Standort Ihres Gateways.

Nächste Schritte