שינוי שער לשימוש ב-OpenAPI 3.x

בדף הזה מוסבר איך לשנות שער API קיים כדי להשתמש במפרט OpenAPI 3.x להגדרת ה-API שלו.

לפני שמתחילים

  • מוודאים שיש לכם מופע קיים של API Gateway שמוגדר עם מפרט OpenAPI 2.0.
  • מתקינים את gcloud CLI. מידע נוסף זמין במאמר התקנת Google Cloud CLI.

שינוי הגדרות של API לשימוש ב-OpenAPI 3.x

כדי לשנות הגדרה קיימת של OpenAPI 2.0 API Gateway כך שתשתמש ב-OpenAPI 3.x, צריך לבצע את השלבים הבאים:

איך מוצאים את הגדרות ה-API הנוכחיות

מאתרים את הגדרת ה-API שמשויכת לשער.

  1. תאר את מופע API Gateway:

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

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫GATEWAY_ID: המזהה של השער.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫GATEWAY_LOCATION: המיקום של השער.

    הפלט יציג את הנתיב apiConfig, לדוגמה:

    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

כדי לקבל את מסמך ה-OpenAPI של הגדרת ה-API שזיהיתם:

  1. תאר את הגדרת ה-API:

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

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫CONFIG_ID: המזהה של הגדרת ה-API.
    • ‫API_ID: מזהה ה-API.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

    הפלט מציג את הקטע openapiDocuments, שמכיל את התוכן בקידוד base64 של מסמך OpenAPI:

    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

כדי לפענח את התוכן של מסמך OpenAPI בקידוד base64:

  1. פענוח הערך contents:

    echo 'IyBvc...' | base64 -d

    מחליפים את IyBvc... בערך contents האמיתי מהשלב הקודם.

    הפלט מציג את מסמך OpenAPI 2.0, לדוגמה:

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

המרת מסמך OpenAPI ל-OpenAPI 3.x

אפשר להשתמש בכלי כדי להמיר את מסמך OpenAPI 2.0 ל-OpenAPI 3.x. לדוגמה, Swagger Editor מספק כלי להמרה.

אחרי ההמרה הראשונית ל-OpenAPI 3.x, צריך להחיל באופן ידני שינויים נוספים במסמך כדי להתאים אותו ל-OpenAPI 3.x ולוודא שהוא תואם לתוספים ולתכונות של API Gateway. לפרטים נוספים על תוסף OpenAPI 3.x שנתמך ב-API Gateway, ראו תוספים של OpenAPI 3.x ב-API Gateway.

בטבלה הבאה מתוארים השינויים הנדרשים:

תכונה OpenAPI 2.0 ‫OpenAPI 3.x תיאור השינוי
מפתח API securityDefinitions securitySchemes מפתחות API משתמשים בתמיכה במפתחות API של OpenAPI שזמינה מחוץ לקופסה. בדרך כלל, כלי המרות מטפלים בזה באופן אוטומטי. אין צורך לבצע שינויים ידניים.
אימות JWT ‫x-google-audiences וכו'. x-google-auth בתוספים של OpenAPI 2.0, מגדירים את OAuth באמצעות תוספים נפרדים במופע securityDefinition. כלי ההמרה ממירים את מופע תוכנית האבטחה ל-#/components/securitySchemes ומשאירים את התוספים. צריך לשנות את התוספים האלה באופן ידני כך שיהיו צאצאים של x-google-auth ולהסיר את הקידומת x-google-. הערכים נשארים ללא שינוי.
מכסה x-google-management, x-google-quota x-google-api-management, x-google-quota בתוספים של OpenAPI 2.0, מגדירים מדדים ומכסות באמצעות x-google-management ומצרפים אותם באמצעות x-google-quota. כלי ההמרה משאירים את התוספים האלה במקומם. העברה ידנית של מדדים והגדרות מכסה מ-x-google-management אל x-google-api-management. משנים את ההגדרות כך שישתמשו במפתחות YAML ומסירים את valueType, metricKind ו-unit. הסרת metricCosts מהמופעים של x-google-quota.
קצה עורפי x-google-backend x-google-api-management, x-google-backend בתוספים של OpenAPI 2.0, מגדירים את ה-backends ב-x-google-backend, וההגדרה חלה במקום שבו היא מוגדרת. בתוספים של OpenAPI 3.x, מגדירים את ה-backend באמצעות x-google-api-management ואז מחילים אותו באמצעות x-google-backend. כלי ההמרות לא מסירים את התוסף הזה. מעבירים את ההגדרה באופן ידני אל x-google-api-management. משנים את המופעים של x-google-backend כך שיפנו להגדרה הזו.
נקודות קצה x-google-endpoints x-google-endpoint, servers בתוספים של OpenAPI 2.0, מגדירים את נקודות הקצה ב-x-google-endpoints. בתוספים של OpenAPI 3.x, משתמשים ב-x-google-endpoint, אבל זהו תוסף של servers ולא של השורש. כלי ההמרה לא מסירים את התוסף הזה. מעבירים את זה ידנית אל servers ומסירים את השדה name. לדוגמה: 
# 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 x-google-api-name x-google-api-management בתוספים של OpenAPI 2.0, מגדירים שמות של API ב-x-google-api-name. בתוספים של OpenAPI 3.x, משתמשים בשדה apiName ב-x-google-api-management. העברה ידנית של ההגדרה הזו אל x-google-api-management.
מתן הרשאה לכל התנועה x-google-allow לא נתמך מסירים את זה ממסמך ה-OpenAPI. ‫API Gateway לא תומך בזה ב-OpenAPI 3.x.

יצירת הגדרת API חדשה

יוצרים הגדרת API חדשה באמצעות מסמך OpenAPI 3.x ששיניתם.

  1. יוצרים את הגדרת ה-API:

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

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫NEW_CONFIG_ID: מזהה חדש להגדרת ה-API.
    • ‫API_ID: מזהה ה-API.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫NEW_API_DEFINITION: הנתיב לקובץ המפרט של OpenAPI 3.x.

עדכון השער

מעדכנים את מופע השער כך שיפנה להגדרת ה-API החדשה מתוך מסמך OpenAPI 3.x ששיניתם.

  1. מעדכנים את השער:

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

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫GATEWAY_ID: המזהה של השער.
    • ‫API_CONFIG: נתיב המשאב המלא של תצורת ה-API החדשה, לדוגמה: projects/PROJECT_ID/locations/global/apis/API_ID/configs/NEW_CONFIG_ID
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫GATEWAY_LOCATION: המיקום של השער.

המאמרים הבאים