Postman Collection Generator

Skill: Postman Collection Generator

Generate importable API client collections (Postman v2.1 or Insomnia) for manual testing and team sharing.

Trigger

When the user asks to create a Postman collection, Insomnia workspace, or export API endpoints for manual testing.

Prerequisites

• [ ] API endpoints identified (from code, OpenAPI spec, or descriptions)
• [ ] Authentication method known
• [ ] Base URL and environments identified

Steps

Step 1: Gather Endpoints

• [ ] Scan route files or OpenAPI spec for all endpoints
• [ ] For each endpoint: method, path, parameters, request body, response shape
• [ ] Group endpoints by resource or feature

Step 2: Define Environment Variables

{
  "id": "env-dev",
  "name": "Development",
  "values": [
    { "key": "baseUrl", "value": "http://localhost:3000/api/v1", "enabled": true },
    { "key": "authToken", "value": "", "enabled": true },
    { "key": "correlationId", "value": "{{$guid}}", "enabled": true }
  ]
}

Environments to create:

• Development — localhost:3000
• Staging — [STAGING_URL]
• Production — [PROD_URL] (read-only requests only)

Step 3: Generate Collection Structure

{
  "info": {
    "name": "{{CONFIG.project.name}} API",
    "_postman_id": "{{$guid}}",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [{ "key": "token", "value": "{{authToken}}", "type": "string" }]
  },
  "variable": [
    { "key": "baseUrl", "value": "http://localhost:3000/api/v1" }
  ],
  "item": []
}

Step 4: Generate Request Items

For each endpoint:

{
  "name": "List Orders",
  "request": {
    "method": "GET",
    "header": [
      { "key": "X-Correlation-Id", "value": "{{correlationId}}" },
      { "key": "Content-Type", "value": "application/json" }
    ],
    "url": {
      "raw": "{{baseUrl}}/orders?cursor=&pageSize=20",
      "host": ["{{baseUrl}}"],
      "path": ["orders"],
      "query": [
        { "key": "cursor", "value": "", "description": "Pagination cursor" },
        { "key": "pageSize", "value": "20", "description": "Items per page (1-100)" }
      ]
    }
  },
  "response": [
    {
      "name": "Success (200)",
      "status": "OK",
      "code": 200,
      "body": "{\"data\": [{\"id\": \"ord_001\", \"status\": \"PENDING\"}], \"meta\": {\"cursor\": \"abc\", \"hasMore\": true}}"
    }
  ]
}

For POST/PUT endpoints:

{
  "name": "Create Order",
  "request": {
    "method": "POST",
    "header": [
      { "key": "X-Correlation-Id", "value": "{{correlationId}}" },
      { "key": "Content-Type", "value": "application/json" }
    ],
    "body": {
      "mode": "raw",
      "raw": "{\n  \"customerId\": \"cust_001\",\n  \"items\": [\n    { \"productId\": \"prod_001\", \"quantity\": 2 }\n  ]\n}",
      "options": { "raw": { "language": "json" } }
    },
    "url": {
      "raw": "{{baseUrl}}/orders",
      "host": ["{{baseUrl}}"],
      "path": ["orders"]
    }
  }
}

Step 5: Add Pre-Request Scripts (Optional)

// Auto-generate correlation ID
pm.variables.set("correlationId", pm.variables.replaceIn("{{$guid}}"));

// Auth token from login response
const authResponse = pm.environment.get("authResponse");
if (authResponse) {
  const token = JSON.parse(authResponse).data.token;
  pm.environment.set("authToken", token);
}

Step 6: Add Test Scripts (Optional)

// Common assertions for all requests
pm.test("Status code is successful", () => {
  pm.expect(pm.response.code).to.be.oneOf([200, 201, 204]);
});

pm.test("Response has correct envelope", () => {
  const json = pm.response.json();
  pm.expect(json).to.have.property("data");
  pm.expect(json).to.have.property("meta");
  pm.expect(json.meta).to.have.property("correlationId");
});

pm.test("Response time < 500ms", () => {
  pm.expect(pm.response.responseTime).to.be.below(500);
});

Step 7: Organize Folders

• [ ] Group by resource: Users, Orders, Products, etc.
• [ ] Add an "Auth" folder with login/register/refresh endpoints
• [ ] Add a "Health" folder with health check endpoints
• [ ] Add an "Admin" folder for administrative endpoints

Step 8: Export and Document

• [ ] Export as Postman Collection v2.1 JSON
• [ ] Export environment files separately
• [ ] Save to docs/api/postman/ or project-standard location
• [ ] Add import instructions to README

Rules

• NEVER include real credentials or tokens in the collection
• NEVER include PII in example request/response bodies
• ALWAYS use environment variables for base URLs and tokens
• ALWAYS include example responses for each endpoint
• Use {{$guid}} for dynamic IDs, {{$timestamp}} for timestamps
• Group endpoints logically by resource, not by HTTP method

Completion

Importable Postman collection JSON with environments, example requests/responses, and test scripts.

If a Step Fails

• No OpenAPI spec: Build from route files and TypeScript types
• Complex auth (OAuth): Add a dedicated "Auth Flow" folder with token exchange steps
• Too many endpoints: Generate for core resources first, expand incrementally
• Insomnia format needed: Convert Postman JSON to Insomnia YAML format