API Documentation (Postman Collection) for Web Application

API Documentation (Postman Collection) for Web Application

Postman Collection is a JSON/YAML format (Collection v2.1) that describes HTTP requests, environment variables, tests, and response examples. Unlike OpenAPI, it is oriented toward manual testing and team collaboration rather than documentation generation. It is published on the Postman API Network or exported as a file for onboarding new developers.

Collection Structure

{
  "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);"
              ]
            }
          }]
        }
      ]
    }
  ]
}

pm.collectionVariables.set is the key pattern: the login test automatically saves the token, and all subsequent requests use {{token}} in the Authorization header.

Environments — Different Environments

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

Separate files env.development.json, env.staging.json, env.production.json are switched in Postman via dropdown. Files with secrets are not committed to the repository (.gitignore), templates without values are committed.

Pre-request Scripts

// Automatically refresh token before each request
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);
    });
}

Generation from OpenAPI

# Import openapi.yaml into collection via Postman CLI
postman collection convert openapi.yaml --output collection.json

# Or via API
curl -X POST https://api.getpostman.com/collections \
  -H "X-Api-Key: $POSTMAN_API_KEY" \
  -d @collection.json

Conversely, you can export Collection to OpenAPI via Postman UI (Export → OpenAPI 3.0).

Newman — Running in CI

npm install -g newman

newman run collection.json \
  --environment env.staging.json \
  --reporters cli,junit \
  --reporter-junit-export results/newman.xml

GitHub Actions integration:

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

--bail failure stops the run on the first error, convenient for smoke tests after deployment.

Publishing Documentation

Postman allows you to publish a collection as interactive documentation on <team>.postman.co/docs. Auto-update via Postman API:

curl -X PUT "https://api.getpostman.com/collections/$COLLECTION_ID" \
  -H "X-Api-Key: $POSTMAN_API_KEY" \
  -d @collection.json

Timeline

Creating a collection for an API (20–30 endpoints, environment variables, tests with auto-token saving): 1–2 days. With Newman in CI, pre-request scripts, documentation publishing: 1 additional day.