תיעוד OpenAPI

כל מפתח מכיר את התחושה: התיעוד אומר דבר אחד, ה-API עושה דבר אחר. עקבת אחרי הדוגמאות בדיוק, אבל אתה מקבל שגיאות 400. אתה מתעמק במימוש בפועל ומגלה שהתיעוד מיושן בחודשים. מישהו שינה שדה חובה ושכח לעדכן את ה-README.

זוהי סחיפת תיעוד, ואיכשהו קיבלנו אותה כדבר נורמלי.

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

מבנה האמת

למסמך OpenAPI יש אנטומיה ספציפית. הבנתה פירושה הבנה של איך נראית "תיאור API הניתן לקריאה על ידי מכונה" בפועל.

Info מזהה את ה-API:

openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
  description: API for managing users in the system

Servers מצהיר היכן ה-API נמצא:

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server

Paths מתאר כל נקודת קצה ומה היא עושה:

paths:
  /users:
    get:
      summary: List all users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  total:
                    type: integer

Components מגדיר חלקים לשימוש חוזר — סכמות, סכמות אבטחה, פרמטרים נפוצים:

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        created_at:
          type: string
          format: date-time
          
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

תחביר $ref מאפשר לך להצביע להגדרות במקום לחזור עליהן. שנה את סכמת User פעם אחת, וכל נקודת קצה שמשתמשת בה מתעדכנת אוטומטית. כך שומרים על מסמך API גדול בריא ומאורגן.

פעולות בפירוט

כל פעולת נקודת קצה מקבלת תיאור מלא:

/users/{userId}:
  get:
    summary: Get a user by ID
    operationId: getUserById
    tags:
      - Users
    parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    responses:
      '200':
        description: User found
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      '404':
        description: User not found
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Error'
    security:
      - bearerAuth: []

ה-operationId הופך לשם פונקציה בעת יצירת קוד לקוח. תגיות מקבצות פעולות קשורות. האבטחה מציינת דרישות אימות. כל תגובה אפשרית — הצלחה וכישלון — מתועדת עם הצורה המדויקת שלה.

מה מאפשרת קריאות מכונה

ברגע שמכונות יכולות לקרוא את תיאור ה-API שלך, הן יכולות לעשות דברים שבני אדם לא יכולים לעולם.

תיעוד אינטראקטיבי — כלים כמו Swagger UI מרנדרים את מסמך ה-OpenAPI שלך כממשק ניתן לעיון ולהפעלה. מפתחים קוראים את התיעוד ובודקים את ה-API באותו מקום. לחיצה על "Execute" מציגה את התגובה בפועל. ללא פקודות curl, ללא הגדרת Postman.

יצירת לקוח מייצרת SDKs ביותר מ-40 שפות ממסמך OpenAPI יחיד:

openapi-generator generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./client

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

middleware לאימות יכול לדחות בקשות שאינן תואמות את המפרט לפני שהן מגיעות לקוד היישום שלך. אם מסמך ה-OpenAPI אומר ש-email הוא שדה חובה ומעוצב כתובת דואר אלקטרוני, בקשות ללא כתובות תקינות נדחות אוטומטית. קוד היישום שלך לעולם לא רואה קלט לא תקין.

שרתי מוק מגיבים עם נתוני דוגמה מהמפרט שלך ללא כל מימוש backend:

prism mock openapi.yaml

צוותי frontend יכולים לבנות מול ה-API לפני שהוא קיים. החוזה הוא המפרט; שרת המוק מכבד אותו.

בדיקות חוזה מאמתות שהמימוש שלך אכן תואם את המפרט. בדיקות נכשלות כשהקוד סוטה מהתיעוד. תיעוד ששקר הופך לכישלון CI.

עיצוב תחילה לעומת קוד תחילה

יש שתי דרכים להגיע למסמך OpenAPI.

עיצוב תחילה כותב את המפרט לפני המימוש. אתה חושב על ה-API שלך כמוצר: מה צריכים הצרכנים? מה הממשק הנקי ביותר? אתה מקבל משוב על העיצוב לפני שאתה כותב שורת קוד אחת. אתה מייצר שלדי שרת מהמפרט וממלא את המימוש.

זה מייצר APIs טובים יותר. זה גם מחייב חשיבה לפני קידוד, מה שחלק מהצוותים מוצאים כלא נוח.

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

רוב הצוותים עם APIs שחשובים — APIs ציבוריים, APIs עם צרכנים רבים, APIs שצריכים להיות יציבים — מוצאים שעיצוב תחילה שווה את ההשקעה המוקדמת.

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

עורכים: Swagger Editor, Stoplight Studio — סביבות מיוחדות עם אימות ותצוגה מקדימה.

תיעוד: Swagger UI, Redoc, RapiDoc — מרנדרים מפרטים כתיעוד יפה ואינטראקטיבי.

מחוללים: OpenAPI Generator, Swagger Codegen — מייצרים לקוחות ושלדי שרת.

מאמתים: Spectral — בודק מפרטים לשגיאות ולהפרות סגנון.

שערים: Kong, AWS API Gateway — מייבאים מפרטים להגדרת ניתוב ואימות.

המערכת האקולוגית קיימת מפני שהתקן קיים. פורמט הניתן לקריאה על ידי מכונה מאפשר עולם שלם של כלים שתיעוד ידני לא יוכל לאפשר לעולם.

מה OpenAPI אינו יכול לעשות

OpenAPI מתאר APIs מסוג REST. אם ה-API שלך הוא GraphQL, מבוסס על WebSocket באופן נרחב, או עוקב אחרי תבניות שאינן ממפות למשאבים ושיטות HTTP, OpenAPI לא יתאים.

APIs גדולים מייצרים מסמכים גדולים. מאות נקודות קצה פירושן אלפי שורות YAML. הארגון הופך לאתגר בפני עצמו.

קוד שנוצר הוא קוד שנוצר. יתכן שלא יתאים לסגנון שלך, יתכן שיכלול תלויות שאינך רוצה, ויתכן שיידרש התאמה לפני שהוא מוכן לסביבת הייצור.

ועדיין צריך לתחזק את המסמך. עיצוב תחילה עוזר, אימות עוזר, אבל מישהו צריך לשמור את המפרט מדויק ככל שה-API מתפתח.

למרות המגבלות הללו, OpenAPI נשאר התקן לתיעוד REST API. החלופה — תיעוד ששקר — גרועה יותר.

שאלות נפוצות על OpenAPI

מה ההבדל בין OpenAPI ל-Swagger?

Swagger היה השם המקורי. כשהמפרט נתרם ל-OpenAPI Initiative בשנת 2015, הוא הפך ל-OpenAPI Specification. Swagger מתייחס כיום לכלים (Swagger UI, Swagger Editor) ולא למפרט עצמו.

האם להשתמש ב-YAML או ב-JSON למסמך ה-OpenAPI שלי?

YAML קריא יותר והוא מה שרוב הצוותים משתמשים בו למפרטים הנכתבים ביד. JSON עובד טוב יותר למפרטים שנוצרים אוטומטית, או כשהכלים שלך מעדיפים אותו. התוכן זהה; רק התחביר שונה.

כיצד מטפלים בגרסאות API עם OpenAPI?

שמור מסמכי OpenAPI נפרדים לכל גרסת API (v1.yaml, v2.yaml). שדה ה-info.version עוקב אחרי גרסת המפרט, בעוד שנתיב ה-URL שלך או כותרת הבקשה מטפלים בדרך כלל בגרסות ה-API.

האם אוכל לייצר מפרט OpenAPI מהקוד הקיים שלי?

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