סקירה כללית על 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

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

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

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

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

בכל מקום בתיעוד של 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.

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