מגבלות על תכונות של OpenAPI 3.x

במסמך הזה מוסברות מגבלות התכונה של שימוש ב-OpenAPI 3.x עם Endpoints.

מידע נוסף על גרסאות נתמכות של מפרט OpenAPI זמין במאמר סקירה כללית על OpenAPI.

מגבלות חדשות ב-OpenAPI 3.x

בקטע הזה מתוארות מגבלות חדשות ב-OpenAPI שנובעות מהתמיכה ב-OpenAPI 3.x.

שרתים

‫OpenAPI 3.x תומך במספר אובייקטים של server כדי להגדיר מארחים ונתיבי בסיס. עם זאת, Cloud Endpoints משתמש רק באובייקט שרת יחיד כדי להגדיר את שם המארח ואת נתיב הבסיס, שמזוהים על ידי התוסף x-google-endpoint.

אפשר להגדיר כמה שרתים במפרט OpenAPI, אבל Cloud Endpoints משתמש רק בשרת עם התוסף x-google-endpoint. אפשר להגדיר את התוסף x-google-endpoint רק בשרת אחד.

ב-Cloud Endpoints נדרש שם מארח, ולכן רק לשרת אחד צריך להיות התוסף x-google-endpoint.

לדוגמה, הגדרות השרת הבאות הן תקינות ל-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

הגדרת השרת הבאה לא חוקית עבור Endpoints:

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: {}

ההגדרה הבאה גם היא לא תקינה ב-Cloud Endpoints:

servers:
  - url: https://my-api.endpoints.my-project-id.cloud.goog

שרתים בכמה קבצים

אם מעלים כמה קובצי OpenAPI, כל הקבצים צריכים לעמוד במגבלות שבקטע servers. אם קובץ אחד מכיל שרת עם הסיומת x-google-endpoint, כל הקבצים חייבים להגדיר שרת עם הסיומת x-google-endpoint.

בנוסף, בכל השרתים עם התוסף x-google-endpoint צריך להשתמש באותו מארח בכתובת ה-URL של השרת, וההגדרה של x-google-endpoint צריכה להיות זהה בכל הקבצים. נתיב הבסיס בכתובת ה-URL של השרת יכול להיות שונה.

כתובת URL יחסית

‫Cloud Endpoints מחייב שם מארח, ולכן הוא לא תומך בכתובות URL יחסיות.

תוספים שלא נתמכים

‫OpenAPI 3.x לא תומך בתוסף x-google-allow.

מגבלות קיימות

בקטע הזה מתוארות מגבלות שהיו ב-OpenAPI 2.0 וממשיכות לחול על OpenAPI 3.x.

היקפי הרשאה שהמערכת התעלמה מהם

אף על פי שאפשר להגדיר היקפי גישה באובייקט של תוכנית אבטחה, מסגרות ESP או Cloud Endpoints לא בודקות אותם.

דרישות אבטחה מרובות

אפשר לציין יותר מדרישת אבטחה אחת במסמך OpenAPI.

  • דרישות אבטחה עם מפתח API: Cloud Endpoints לא תומך בדרישות אבטחה חלופיות (לוגיות OR) כשאחת מהסכימות היא מפתח API. ‫Cloud Endpoints תומך בחיבורים (AND לוגי), כך שאפשר לדרוש גם מפתח API וגם אימות OAuth2.

  • דרישות אבטחה ל-OAuth2: Cloud Endpoints תומך בדרישות אבטחה חלופיות (לוגיות OR) עבור סכימות אימות שונות של OAuth2. ‫Cloud Endpoints לא תומך בחיבורים (logical AND) אלא אם דרישת האבטחה הנוספת היא מפתח API.

  • דרישות אבטחה אופציונליות: ‏ OpenAPI 3 תומך באבטחה אופציונלית על ידי הכללת דרישה ריקה ({}). מפתח API תומך באפשרות הזו, אבל OAuth לא.

אימות הגדרת האבטחה

ב-OpenAPI 3.x, שימוש בסכימת אבטחה לא מוגדרת מוביל לשגיאה, ו-Cloud Endpoints דוחה את המפרט. זהו שינוי מ-OpenAPI 2.0, שבו נוצרת רק אזהרה.

תבניות של נתיבי כתובות URL

‫Cloud Endpoints תומך רק בפרמטרים של תבניות נתיבי URL שתואמים לפלחי נתיבים שלמים (מופרדים באמצעות /). ‫Cloud Endpoints לא תומך בפרמטרים של פלחי נתיבים חלקיים.

לדוגמה, Cloud Endpoints תומך ב-/items/{itemId}, אבל לא ב-/items/overview.{format}.

פעולות בנתיב הבסיסי של כתובת ה-URL‏ /

למרות שמסמך OpenAPI מקבל פעולות בנתיב הבסיס /, Extensible Service Proxy דוחה בקשות לנתיב הבסיס. המגבלה הזו לא חלה על ESPv2, שתומך בנתיב הבסיס.

פרמטרים, סכימות, גופי בקשות וסוגים

‫Extensible Service Proxy ו-ESP מתעלמים מרוב הפרמטרים, הסכימות, תוכן הבקשה והגדרות הסוג. ‫Extensible Service Proxy ו-ESP לא אוכפים פרמטרים נדרשים והגדרות סוג, והם מעבירים בקשות ל-API שלכם.

‫Extensible Service Proxy ו-ESP תומכים רק בסוגים פרימיטיביים בפרמטרים של בקשות.

הפניות לסוגים חיצוניים

‫Cloud Endpoints לא תומך בהפניות לסוגים מחוץ למסמך OpenAPI. לדוגמה, אי אפשר להשתמש ב$ref כדי להפנות לכתובת URL חיצונית.

כתובת מותאמת אישית של מארח השירות לניוד

אי אפשר להשתמש ביציאות מותאמות אישית ב-url של אובייקט servers.

מגבלות על כינויי YAML

מסמך OpenAPI יכול להכיל עד 200 צמתי כינוי של YAML.

גוף הבקשה שלא חוזר על עצמו

אפשר להגדיר רק requestBody אחד לכל פעולה, והוא צריך להיות מסוג לא חוזר.