---
name: postman-doc
description: Generate Postman collection JSON for API endpoints. Use when user says "postman", "buat postman", "import postman", "postman collection", or "/postman-doc <endpoint>". Creates importable Postman collection with request examples, headers, and response samples.
---

# Generate Postman Collection

Generate Postman-importable collection for "$ARGUMENTS".

## Before You Start

1. Identify the endpoint(s) — find route definitions, controllers, validators
2. Check if there's existing API contract documentation in `.claude/api-contract/`
3. Determine base URL from environment (default: `{{base_url}}` variable)

## Steps

### 1. Find the Endpoint(s)

Search in route files:

- `src/modules/v2/**/*.routes.js`
- `routes/v2/*.js`
- `routes/v1/*.js` (if V2 not found)

For each endpoint, identify:

- HTTP method (GET/POST/PUT/DELETE)
- Full URL path
- Query parameters (from validator)
- Request body (from validator)
- Access control roles
- Response structure (from processor/service)

### 2. Read the Code

For each endpoint:

- Read the validator to get required/optional params
- Read the processor to understand response structure
- Read the controller for any special handling

### 3. Generate Postman Collection JSON

Create a Postman Collection v2.1 format JSON file at `.claude/api-contract/postman/` directory.

Structure:

```json
{
  "info": {
    "name": "<Collection Name>",
    "description": "<Description>",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    { "key": "baseUrl", "value": "http://localhost:3000" },
    { "key": "token", "value": "" }
  ],
  "item": [
    {
      "name": "<Endpoint Name>",
      "request": {
        "method": "GET|POST|PUT|DELETE",
        "header": [
          { "key": "Authorization", "value": "Bearer {{TOKEN_USER_ACCESS}}" },
          { "key": "Content-Type", "value": "application/json" }
        ],
        "url": {
          "raw": "{{baseUrl}}/v2/...",
          "host": ["{{baseUrl}}"],
          "path": ["v2", "..."],
          "query": [...]
        },
        "body": { ... }
      },
      "response": [
        {
          "name": "Success",
          "status": "OK",
          "code": 200,
          "body": "..."
        }
      ]
    }
  ]
}
```

### 4. Output

- Save collection JSON to `.claude/api-contract/postman/<collection-name>.json`
- Inform user they can import via: Postman → Import → Upload File → select the JSON
- If MCP Postman server is configured in `.mcp.json`, offer to push directly via MCP

## Description Format (WAJIB diikuti)

Semua deskripsi request di Postman HARUS mengikuti format standar berikut (referensi: Publishing → Event → Internal):

### Format Request Description

```markdown
### [Nama Endpoint]

[Paragraf penjelasan singkat — apa yang dilakukan endpoint ini, kapan digunakan, dan konteks penggunaannya.]

---

- **Headers:**
  - `Authorization` (Bearer token, Required): Token JWT untuk otentikasi.
  - `Content-Type` (application/json, Required): Format body request.

- **Query Parameters:** / **Body Parameters (JSON):** / **Body Parameters (form-data):**
  - `param_name` (Type, Required/Optional): Penjelasan parameter.
  - `param_name` (Type, Optional): Penjelasan. Default: `value`.

[Optional: catatan/warning tambahan dengan emoji ⚠️]
```

### Format Folder Description

```markdown
[Paragraf prose yang menjelaskan isi folder, tujuan, dan use case umum.]

Endpoint dalam folder ini memungkinkan pengguna untuk:

- [Use case 1]
- [Use case 2]
```

### Aturan Penulisan

1. Gunakan Bahasa Indonesia untuk deskripsi.
2. Heading request selalu `### [Nama]` (H3).
3. Pisahkan paragraf penjelasan dan parameter dengan `---` (horizontal rule).
4. Parameter ditulis sebagai nested bullet: `- **Section:** \n    - \`param\` (Type, Required): Desc.`
5. Gunakan backtick untuk nama parameter, value default, dan tipe data.
6. Jangan gunakan `\n` literal — gunakan newline asli di Postman API.
7. Catatan/warning gunakan prefix `⚠️ **Catatan:**`.

## Rules

- Always use `{{baseUrl}}` and `{{TOKEN_USER_ACCESS}}` variables (not hardcoded)
- Include example response bodies based on actual processor output
- Group related endpoints in folders
- Add description to each request AND folder explaining what it does
- Include both success and error response examples
- Mark required params clearly in description
- Follow the Description Format above for ALL Postman descriptions