digiqagent 1.2.0

package/skills/postman-collection-generator/SKILL.md

@@ -0,0 +1,310 @@
+---
+name: postman-collection-generator
+description: Use when generating Postman collections from an existing OpenAPI/Swagger spec, codebase routes, or API design document for manual developer testing
+---
+
+# Postman Collection Generator
+
+## Overview
+
+Produce a complete, ready-to-import Postman Collection v2.1 JSON file from an OpenAPI spec, codebase analysis, or API design document. Includes organized folders, realistic example data, environment variables, and pre-request scripts.
+
+**Core principle:** Developers import, configure the environment, and start testing immediately. Zero guesswork.
+
+## When to Use
+
+- API has an OpenAPI spec and needs a Postman collection
+- Developer needs to manually test API endpoints
+- No existing Postman collection, or existing one is outdated
+- Before generating test suites (prerequisite for `digiqagent:postman-test-suite-generator`)
+
+## Input Detection
+
+### Preferred — Existing OpenAPI Spec
+
+Check for `openapi.yaml`, `swagger.yaml`, `openapi.json`, or `swagger.json` in the project.
+
+If no spec exists, recommend running `digiqagent:swagger-generator` first. A spec ensures nothing is missed.
+
+### Alternative — Codebase Scan
+
+If no spec is available and the developer wants to skip spec generation, scan the codebase directly using the same framework detection as the swagger-generator skill. Capture endpoints, methods, request/response shapes, and auth requirements.
+
+### Alternative — API Design Document
+
+Parse a provided requirements or design document to extract endpoints, parameters, and expected behaviors.
+
+## Generation Process
+
+### Step 1 — Read Source
+
+Parse the OpenAPI spec (or codebase/design doc) and extract:
+- Every endpoint: method, path, operationId, summary
+- Parameters: path, query, header — with types and examples
+- Request bodies: schemas with example values
+- Response schemas: for status code validation later
+- Security requirements: which endpoints need auth
+- Server URLs: for environment variable defaults
+
+### Step 2 — Organize into Folders
+
+Group requests by **tag** (from OpenAPI) or **resource** (from URL path):
+
+```
+Collection Root
+├── Auth
+│   ├── Register
+│   ├── Login
+│   └── Refresh Token
+├── Users
+│   ├── List Users
+│   ├── Create User
+│   ├── Get User by ID
+│   ├── Update User
+│   └── Delete User
+├── Products
+│   ├── List Products
+│   ├── Create Product
+│   └── ...
+└── System
+    └── Health Check
+```
+
+**Ordering within folders:**
+1. Auth/setup operations first
+2. Create (POST)
+3. List (GET collection)
+4. Get by ID (GET single)
+5. Update (PUT/PATCH)
+6. Delete (DELETE)
+
+This ordering mirrors the natural developer workflow: create something, verify it exists, modify it, remove it.
+
+### Step 3 — Build Requests
+
+For each endpoint, generate:
+
+```json
+{
+  "name": "Create User",
+  "request": {
+    "method": "POST",
+    "header": [
+      {
+        "key": "Content-Type",
+        "value": "application/json"
+      },
+      {
+        "key": "Authorization",
+        "value": "Bearer {{authToken}}"
+      }
+    ],
+    "url": {
+      "raw": "{{baseUrl}}/api/users",
+      "host": ["{{baseUrl}}"],
+      "path": ["api", "users"],
+      "query": []
+    },
+    "body": {
+      "mode": "raw",
+      "raw": "{\n  \"name\": \"Jane Smith\",\n  \"email\": \"jane.smith@example.com\",\n  \"password\": \"SecureP@ss123\",\n  \"role\": \"user\"\n}",
+      "options": {
+        "raw": {
+          "language": "json"
+        }
+      }
+    }
+  }
+}
+```
+
+**Example data rules:**
+- Use realistic but obviously fake data (not `test`, `foo`, `bar`)
+- Names: `Jane Smith`, `Alex Johnson` — not `string` or `user1`
+- Emails: `jane.smith@example.com` — not `test@test.com`
+- IDs: use `{{userId}}` variables for chained requests
+- Passwords: `SecureP@ss123` — shows valid format
+- Dates: recent realistic dates, not `2000-01-01`
+- Numbers: realistic values (age: 28, price: 49.99)
+
+### Step 4 — Add Environment Variables
+
+Generate variables using `{{variable}}` syntax:
+
+| Variable | Description | Default Value |
+|----------|-------------|---------------|
+| `baseUrl` | API base URL | `http://localhost:3000` |
+| `authToken` | JWT/Bearer token | _(empty, populated by login)_ |
+| `refreshToken` | Refresh token | _(empty, populated by login)_ |
+| `userId` | Current user ID | _(empty, populated by create/login)_ |
+| `resourceId` | Last created resource ID | _(empty, populated by create)_ |
+| `adminToken` | Admin auth token | _(empty, populated by admin login)_ |
+
+Add any API-specific variables discovered during analysis (API keys, tenant IDs, etc.).
+
+### Step 5 — Include Pre-Request Scripts
+
+Add scripts where they enable a smoother workflow:
+
+**Collection-level pre-request script** (runs before every request):
+```javascript
+// Auto-refresh token if expired (when refreshToken exists)
+if (pm.environment.get("authToken") && pm.environment.get("tokenExpiry")) {
+    const expiry = parseInt(pm.environment.get("tokenExpiry"));
+    if (Date.now() >= expiry) {
+        console.log("Token expired, refreshing...");
+        // Token refresh logic or flag for manual refresh
+    }
+}
+```
+
+**Login endpoint test script** (store token after successful login):
+```javascript
+if (pm.response.code === 200) {
+    const response = pm.response.json();
+    pm.environment.set("authToken", response.token || response.accessToken);
+    if (response.refreshToken) {
+        pm.environment.set("refreshToken", response.refreshToken);
+    }
+    if (response.user && response.user.id) {
+        pm.environment.set("userId", response.user.id);
+    }
+}
+```
+
+**Create endpoint test script** (capture created resource ID):
+```javascript
+if (pm.response.code === 201) {
+    const response = pm.response.json();
+    pm.environment.set("resourceId", response.id || response.data?.id);
+}
+```
+
+### Step 6 — Write Collection File
+
+Output as Postman Collection v2.1 JSON:
+- **Default filename:** `postman_collection.json` at project root
+- **User override:** write to specified path
+
+The file must conform to the Postman Collection v2.1 schema:
+
+```json
+{
+  "info": {
+    "name": "<Project Name> API",
+    "_postman_id": "<generated-uuid>",
+    "description": "<from OpenAPI info.description>",
+    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+  },
+  "item": [ /* folders and requests */ ],
+  "event": [ /* collection-level scripts */ ],
+  "variable": [ /* collection variables */ ]
+}
+```
+
+### Step 7 — Generate Environment File
+
+Create a companion `postman_environment.json`:
+
+```json
+{
+  "name": "<Project Name> - Local",
+  "values": [
+    {
+      "key": "baseUrl",
+      "value": "http://localhost:3000",
+      "type": "default",
+      "enabled": true
+    },
+    {
+      "key": "authToken",
+      "value": "",
+      "type": "secret",
+      "enabled": true
+    },
+    {
+      "key": "refreshToken",
+      "value": "",
+      "type": "secret",
+      "enabled": true
+    },
+    {
+      "key": "userId",
+      "value": "",
+      "type": "default",
+      "enabled": true
+    }
+  ],
+  "_postman_variable_scope": "environment"
+}
+```
+
+If multiple server URLs exist in the OpenAPI spec, generate separate environment files:
+- `postman_environment_local.json`
+- `postman_environment_staging.json`
+- `postman_environment_production.json`
+
+## Developer Workflow
+
+Include these instructions in the collection description so developers know what to do:
+
+```
+## Getting Started
+
+1. Import `postman_collection.json` into Postman
+2. Import `postman_environment.json` as an environment
+3. Select the imported environment in the top-right dropdown
+4. Update `baseUrl` if your server runs on a different port
+5. Run the "Login" request first to populate the auth token
+6. Start testing endpoints — IDs are auto-captured from create responses
+
+## Running the Full Collection
+- Click "Run" on the collection folder
+- Use Postman Runner for sequential execution
+- Auth requests run first, populating tokens for subsequent requests
+```
+
+## Red Flags — STOP and Fix
+
+| Problem | Fix |
+|---------|-----|
+| Request has hardcoded URL | Use `{{baseUrl}}` variable |
+| Auth token hardcoded in header | Use `{{authToken}}` variable |
+| Request body uses placeholder data (`string`, `0`) | Use realistic example values |
+| No folders — flat request list | Organize by resource/tag |
+| Auth endpoint has no test script to store token | Add token extraction script |
+| Create endpoint doesn't capture ID | Add script to set `{{resourceId}}` |
+| Missing Content-Type header on POST/PUT | Add `Content-Type: application/json` |
+| Environment file missing | Generate it alongside the collection |
+| Path parameters not using variables | Use `{{userId}}` etc. for chained requests |
+
+## Verification Checklist
+
+Before marking generation complete:
+
+- [ ] Every endpoint from the spec/codebase has a corresponding request
+- [ ] Requests organized into logical folders
+- [ ] All URLs use `{{baseUrl}}` variable
+- [ ] Auth endpoints include token-capture test scripts
+- [ ] Create endpoints include ID-capture test scripts
+- [ ] Request bodies have realistic example data
+- [ ] Environment file generated with all necessary variables
+- [ ] Collection imports successfully into Postman (valid JSON)
+- [ ] File written and path confirmed to user
+
+Apply `digiqagent:verification-before-completion` — evidence before claims.
+
+## Common Patterns
+
+See @collection-patterns.md for:
+- Auth flow patterns (login -> token storage -> authenticated requests)
+- CRUD operation ordering
+- Chained request patterns
+- File upload requests
+- Multipart form data
+
+## Next Steps
+
+After generating the collection:
+1. Use `digiqagent:postman-test-suite-generator` to add positive and negative test scenarios
+2. Developer imports into Postman and runs manually to verify API behavior