rc-postman

Postman Collection

Keep a Postman collection synchronized with the API's real routes and request contracts. Build requests from what the code accepts, not from guesses. This skill is standalone and stack-agnostic; it detects how the project defines HTTP endpoints.

Required Inputs

• None. Operates on the current repository.
• Optional: the collection output directory (default .techdocs/docs/postman/), the collection name (default derived from the project name), and which environments to emit (default Local).

Workflow

1. Locate the collection. Search for an existing *.postman_collection.json (.techdocs/docs/postman/, .techdocs/docs/, docs/). If found, read it to preserve its structure and reuse its directory; otherwise default the output to .techdocs/docs/postman/, creating the directory if needed.

2. Discover HTTP endpoints from source. Detect the routing mechanism and enumerate every HTTP endpoint with its method, full path, and handler reference. Routing lives in different places per stack:

   • Framework routers (Express, Fastify, NestJS, Gin, Echo, Spring controllers, FastAPI/Flask, Rails routes, ASP.NET controllers).
   • Infrastructure manifests (serverless.yml, API Gateway / OpenAPI definitions, k8s ingress) — use http events; ignore non-HTTP triggers (queue, schedule, stream).
   • Exclude non-HTTP entry points (queue consumers, cron jobs, background workers).

3. Extract the request contract for each endpoint from its handler/validation layer:

   • Path parameters — name, type, example.
   • Query parameters — name, type, required/optional, default.
   • Body — fields with type, required/optional, defaults, and constraints, read from the validation schema or DTO (Zod, Joi, Pydantic, class-validator, Go structs + tags, Java/C# DTOs).
   • Headers — required headers (content type, auth, custom context headers).
   • Capture a one-line purpose from the handler's doc comment or, failing that, its name.

4. Build or update the collection (Postman Collection Format v2.1.0):

   • Schema: https://schema.getpostman.com/json/collection/v2.1.0/collection.json.
   • Folders: group requests by resource or domain (one folder per resource/tag). Preserve any existing folder organization and non-HTTP helper folders the user maintains.
   • Requests: for each endpoint set method, the URL using {{baseUrl}} as host with the exact path, path variables in Postman :param syntax (with example values in the URL variable block), required headers, and — for body methods — a realistic example JSON body covering every schema field. Use type-appropriate example values (valid UUIDs for IDs, E.164 for phones, ISO 8601 for timestamps, enum members for enums, null for nullable fields).
   • Collection variables: keep {{baseUrl}} and any existing variables; do not hardcode hosts.
   • Add new endpoints to the most appropriate folder; remove requests whose endpoints no longer exist in source and report them.