תיעוד API עם אוסף Postman

{
  "info": {
    "name": "MyApp API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://api.example.com/v1"
    },
    {
      "key": "token",
      "value": ""
    }
  ],
  "item": [
    {
      "name": "Auth",
      "item": [
        {
          "name": "Login",
          "request": {
            "method": "POST",
            "url": "{{base_url}}/auth/login",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\"email\": \"[email protected]\", \"password\": \"secret\"}"
            }
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "pm.test('Status 200', () => pm.response.to.have.status(200));",
                  "const json = pm.response.json();",
                  "pm.collectionVariables.set('token', json.data.token);"
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}

{ "info": { "name": "MyApp API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "variable": [ { "key": "base_url", "value": "https://api.example.com/v1" }, { "key": "token", "value": "" } ], "item": [ { "name": "Auth", "item": [ { "name": "Login", "request": { "method": "POST", "url": "{{base_url}}/auth/login", "header": [{ "key": "Content-Type", "value": "application/json" }], "body": { "mode": "raw", "raw": "{\"email\": \"[email protected]\", \"password\": \"secret\"}" } }, "event": [{ "listen": "test", "script": { "exec": [ "pm.test('Status 200', () => pm.response.to.have.status(200));", "const json = pm.response.json();", "pm.collectionVariables.set('token', json.data.token);" ] } }] } ] } ] } — תבנית מפתח: בדיקת ההתחברות שומרת אוטומטית את ה-token, וכל הבקשות הבאות משתמשות ב-pm.collectionVariables.set בכותרת Authorization.

אילו אלמנטים הופכים Collection למסמך חי?

סביבות — סביבות שונות

{
  "name": "Production",
  "values": [
    {
      "key": "base_url",
      "value": "https://api.example.com/v1",
      "enabled": true
    },
    {
      "key": "token",
      "value": "",
      "enabled": true
    }
  ]
}

קבצים נפרדים {{token}}, { "name": "Production", "values": [ { "key": "base_url", "value": "https://api.example.com/v1", "enabled": true }, { "key": "token", "value": "", "enabled": true } ] } , env.development.json — מוחלפים ב-Postman דרך תפריט נפתח. תבניות ללא ערכים נשלחות ל-repository, קבצים עם סודות לא. לנתונים רגישים, השתמשו במשתני מערכת CI במקום לאחסן אותם ב-collection.

סקריפטים לפני בקשה ובדיקות אוטומטיות

סקריפטים לפני בקשה רצים לפני כל בקשה. דוגמה — חידוש token אוטומטי:

const tokenExpiry = pm.collectionVariables.get('token_expiry');
if (!tokenExpiry || Date.now() > parseInt(tokenExpiry)) {
    pm.sendRequest({
        url: pm.variables.get('base_url') + '/auth/refresh',
        method: 'POST',
        header: {
            'Content-Type': 'application/json'
        },
        body: {
            mode: 'raw',
            raw: JSON.stringify({
                refresh_token: pm.collectionVariables.get('refresh_token')
            })
        }
    }, (err, res) => {
        pm.collectionVariables.set('token', res.json().data.access_token);
        pm.collectionVariables.set('token_expiry', Date.now() + 3600000);
    });
}

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

אילו טעויות נעשות ביצירת Postman Collection?

• משתני סביבה חסרים — תצטרכו לשנות את ה-URL בכל בקשה.
• אין סקריפטים לפני בקשה לחידוש token — בדיקות ייכשלו לאחר פקיעת ההפעלה.
• בדיקות בודקות רק קוד סטטוס — הוסיפו אימות סכמת JSON באמצעות env.staging.json.
• ה-collection לא מנוהל גרסאות — שמרו אותו ב-Git לצד הקוד.
• Newman לא מוגדר ב-CI — בדיקות לא רצות אוטומטית לאחר פריסה.

מה כלול בתיעוד API סוהר?

אנו מספקים:

• Postman Collection מוכן (מבנה, משתנים, תגובות לדוגמה).
• סביבות לכל הסביבות (dev/staging/production).
• מערכת בדיקות אוטומטיות עם בדיקות סטטוס וסכמת תגובה.
• סקריפטים לפני בקשה לאימות אוטומטי.
• אינטגרציה עם CI דרך Newman (GitHub Actions, GitLab CI).
• פרסום תיעוד ב-Postman API Network.
• הדרכת צוות לעבודה עם ה-collection.

הזמינו פיתוח של Postman Collection וקבלו תיעוד מעודכן עם בדיקות אוטומטיות.

השוואה: Postman Collection מול OpenAPI

Postman Collection מתאים יותר לבדיקות וניפוי שגיאות מהירים, במיוחד בעבודה צוותית. עם זאת, OpenAPI שימושי ליצירת לקוחות ושרתים.

תהליך ולוח זמנים

לוח זמנים: collection בסיסי (20–30 נקודות קצה) — 1–2 ימים. עם אינטגרציה ופרסום — יום נוסף אחד. לוח זמנים מדויק מחושב לאחר הביקורת.

מדריך שלב אחר שלב להגדרת Newman ב-CI

1. התקינו Newman גלובלית: const tokenExpiry = pm.collectionVariables.get('token_expiry'); if (!tokenExpiry || Date.now() > parseInt(tokenExpiry)) { pm.sendRequest({ url: pm.variables.get('base_url') + '/auth/refresh', method: 'POST', header: { 'Content-Type': 'application/json' }, body: { mode: 'raw', raw: JSON.stringify({ refresh_token: pm.collectionVariables.get('refresh_token') }) } }, (err, res) => { pm.collectionVariables.set('token', res.json().data.access_token); pm.collectionVariables.set('token_expiry', Date.now() + 3600000); }); } .
2. צרו קובץ pm.response.to.have.jsonSchema עם פקודות להרצה.
3. בקונפיגורציית CI (GitHub Actions) הוסיפו שלב:

- name: Run API Tests run: | newman run collection.json \ --environment env.ci.json \ --bail failure 

4. לדוחות, השתמשו ב-pm.test.
5. תזמנו הרצה לאחר כל פריסה.

npm install -g newman עוצר את ההרצה בשגיאה הראשונה — נוח לבדיקות עשן לאחר פריסה.

למה לבחור בנו?

מעל 10 שנות ניסיון בפיתוח API ו-50+ פרויקטי תיעוד. אנו מבטיחים שה-collection מעודכן ומוכן לשימוש מיידי. ההשקעה ביצירת Postman Collection משתלמת: חיסכון ממוצע בתקציב על בדיקות הוא 30%. קבלו ייעוץ על ה-API שלכם — צרו קשר.