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

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

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

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

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

‫Cloud Endpoints תומך בגרסאות הבאות של OpenAPI:

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

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

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

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

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

בכל מקום בתיעוד של Cloud Endpoints שמוזכרת בו OpenAPI 3.x, הכוונה היא לכל הגרסאות הנתמכות של OpenAPI 3.

יתרונות

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

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

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

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

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

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

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

OpenAPI 2.0

אם אתם חדשים ב-OpenAPI, כדאי לעיין באתר Swagger basic structure. באתר הזה יש מסמך לדוגמה של 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: API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
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, כדאי לעיין במפרט OpenAPI, שכולל מסמך לדוגמה של 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
servers:
  - url: https://API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
    x-google-endpoint: {}
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 יכולים להתעניין בפרויקט flask-swagger, ומפתחי Node יכולים להתעניין בפרויקט swagger-node-express.

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

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