סקירה כללית על OpenAPI

‫API Gateway תומך בממשקי API שמתוארים באמצעות גרסאות נתמכות של מפרט OpenAPI.

אפשר להטמיע את ה-API באמצעות כל מסגרת REST שזמינה לציבור, כמו Django או Jersey.

אתם מתארים את ה-API בקובץ YAML שנקרא מסמך OpenAPI. בדף הזה מתוארים כמה מהיתרונות של שימוש ב-OpenAPI, מוצג מסמך OpenAPI בסיסי ומסופק מידע נוסף שיעזור לכם להתחיל להשתמש ב-OpenAPI.

גרסאות OpenAPI נתמכות

‫API Gateway תומך בגרסאות הבאות של OpenAPI:

  1. ‫OpenAPI 2.0 (לשעבר Swagger)
  2. ‫OpenAPI 3.0.x

מפרטים רשמיים לכל גרסה זמינים ב-OpenAPI Initiative.

תמיכה בגרסאות תיקון

מפרט OpenAPI מציין שגרסאות תיקון (לדוגמה, 3.0.1,‏ 3.0.2) כוללות רק תיקונים או הבהרות, ולא מוסיפות תכונות חדשות. כתוצאה מכך, API Gateway תומך בכל גרסאות התיקון של 3.0.

הסברים על המונחים

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

יתרונות

אחד היתרונות העיקריים של שימוש ב-OpenAPI הוא תיעוד. אחרי שיש לכם מסמך OpenAPI שמתאר את ה-API, אתם יכולים ליצור מאמרי עזרה ל-API.

יש עוד יתרונות לשימוש ב-OpenAPI. לדוגמה, אתם יכולים:

  • יצירה של ספריות לקוח בעשרות שפות
  • יצירת קבצים זמניים של שרת
  • שימוש בפרויקטים כדי לאמת את התאימות וליצור דוגמאות

המבנה הבסיסי של מסמך OpenAPI

מסמך OpenAPI מתאר את הממשק של ה-API בארכיטקטורת REST, ומגדיר מידע כמו:

  • השם והתיאור של ה-API
  • נקודות הקצה (הנתיבים) הנפרדות ב-API
  • איך המתקשרים מאומתים

המבנה של מסמך OpenAPI תלוי בגרסת OpenAPI שבה אתם משתמשים. בדוגמאות הבאות מתואר המבנה של OpenAPI 2.0 ו-OpenAPI 3.x.

OpenAPI 2.0

אם אתם חדשים ב-OpenAPI, כדאי לעיין במבנה הבסיסי של Swagger, שכולל מסמך לדוגמה של OpenAPI (שנקרא גם מפרט Swagger) והסבר קצר על כל קטע בקובץ. הדוגמה הבאה ממחישה את המבנה הבסיסי הזה:

swagger: "2.0"
info:
  title: API_ID optional-string
  description: "Get the name of an airport from its three-letter IATA code."
  version: "1.0.0"
host: DNS_NAME_OF_DEPLOYED_API
schemes:
  - "https"
paths:
  "/airportName":
    get:
      description: "Get the airport name for a given IATA code."
      operationId: "airportName"
      parameters:
        -
          name: iataCode
          in: query
          required: true
          type: string
      responses:
        200:
          description: "Success."
          schema:
            type: string
        400:
          description: "The IATA code is invalid or missing."

‫OpenAPI 3.x

אם אתם חדשים ב-OpenAPI, כדאי לעיין במבנה הבסיסי של Swagger, שכולל מסמך לדוגמה של OpenAPI והסבר על כל קטע בקובץ. הדוגמה הבאה ממחישה את המבנה הבסיסי הזה:

openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Get the name of an airport from its three-letter IATA code
  version: 1.0.0
x-google-api-management:
  backends:
    BACKEND_NAME
      address: https://BACKEND_URL/airportNameGET
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
x-google-backend: BACKEND_NAME
paths:
  /airportName:
    get:
      summary: Get the airport name for a given IATA code
      operationId: airportName
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string
      parameters:
        - name: iataCode
          in: query
          required: true
          schema:
            type: string

בנוסף למבנה הבסיסי, משתמשים בקובץ openapi.yaml כדי להגדיר:

יצירת מסמך OpenAPI

יכול להיות שתוכלו ליצור מסמך OpenAPI, בהתאם לשפה שבה אתם משתמשים. ב-Java, יש פרויקטים בקוד פתוח גם ל-Jersey וגם ל-Spring, שיכולים ליצור מסמך OpenAPI מתוך הערות. יש גם תוסף Maven. מפתחי Python ו-Node יכולים להתעניין בפרויקט OpenAPI.Tools.

קהילת OpenAPI מפתחת כל הזמן כלים שיעזרו לכם ליצור מסמכי OpenAPI (ובחלק מהשפות, ליצור אותם באופן אוטומטי). מידע נוסף זמין במאמר בנושא מפרט OpenAPI.

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