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

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

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

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

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

שרתים

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

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

לדוגמה, ההגדרות הבאות הן תקינות ל-API Gateway:

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

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

ההגדרה הבאה לא תקינה כי היא מכילה כמה תוספים של x-google-endpoint:

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

ההגדרה הבאה תקפה ל-API Gateway, אבל API Gateway מתעלם מאובייקט השרת:

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

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

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

כתובת URL יחסית

ב-API Gateway, כתובות URL יחסיות באובייקט servers נחשבות לנתיב בסיסי בפני עצמו, כי לא נדרש שם מארח במפרט. ההתנהגות הזו שונה מההתנהגות הרגילה של OpenAPI, שבה כתובות URL יחסיות נפתרות מול השרת שמארח את הגדרת OpenAPI. לדוגמה, API Gateway מתייחס ל-url: /v1 כאל basepath.

נתיבי בסיס חייבים להתחיל בסימן '/'. API Gateway דוחה כתובות URL שלא כוללות סכימה או שלא מתחילות בסימן '/' כדי לציין נתיב בסיס.

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

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

מגבלות על גודל הקובץ

ב-API Gateway יש מגבלת גודל כוללת של 10MB ומגבלת מספר קבצים של 50 לקבצים מסוג OpenAPI 3.x שמועלים.

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

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

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

למרות ש-API Gateway מקבל מסמכי OpenAPI עם היקפי הרשאות שמוגדרים באובייקט של תוכנית אבטחה, הוא לא בודק את היקפי ההרשאות האלה ולא אוכף אותם.

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

• דרישות לגבי מפתח API: ‏ API Gateway לא תומך בדרישות אבטחה חלופיות (לוגיות OR) אם אחת מהסכימות היא מפתח API. עם זאת, API Gateway תומך בחיבורים (logical AND), כך שאפשר לדרוש גם מפתח API וגם אסימון OAuth2.
• דרישות OAuth2: API Gateway תומך בדרישות אבטחה חלופיות (לוגיות OR) עבור תוכניות אבטחה שונות של OAuth2. ‫API Gateway לא תומך בחיבורים (logical AND) אלא אם דרישת האבטחה הנוספת היא מפתח API.
• אבטחה אופציונלית: אפשר להשתמש בדרישת אבטחה ריקה (- {}) כדי להפוך את האבטחה לאופציונלית עבור מפתח API, אבל API Gateway לא תומך באפשרות הזו עבור OAuth.

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

‫API Gateway ידחה מפרט OpenAPI 3.x שנעשה בו שימוש בדרישת אבטחה ללא הגדרה תואמת בקטע securityDefinitions.

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

API Gateway תומך רק בפרמטרים של תבנית נתיב כתובת ה-URL שמייצגים פלחים שלמים של נתיב, לדוגמה, /items/{itemId}. ‫API Gateway לא תומך בפרמטרים שמתאימים לפלחים חלקיים ודוחה אותם, לדוגמה, /items/prefix_{id}_suffix.

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

‫API Gateway מקבל מסמכי OpenAPI עם הגדרות שונות של פרמטרים וסוגים (לדוגמה, פרמטרים של required ופורמטים של מערכים), אבל הוא לא אוכף אותם. ‫API Gateway מעביר בקשות נכנסות ל-API שלכם ללא קשר להגדרות האלה.

‫API Gateway תומך רק בסוגים פרימיטיביים בפרמטרים של בקשות.

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

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

יציאה מותאמת אישית בכתובת המארח

‫API Gateway לא מאפשר יציאות מותאמות אישית בשדה servers.url של מסמך OpenAPI.

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

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