AICHE +Postman Integration

The short answer: open a Postman request, click into the description field, press ⌃+⌥+R (Mac) or Ctrl+Alt+R (Windows/Linux), speak for 30-60 seconds, and AICHE inserts the transcribed documentation at your cursor position.

Postman has genuinely good documentation features. Collection descriptions, request descriptions, parameter documentation, example explanations, folder overviews. The tooling exists. The problem is that nobody uses it because typing API documentation is tedious.

Think about the last API collection you built. How many requests have descriptions? How many parameters have explanations beyond the field name? How many error responses are documented? For most developers, the answer is "almost none," and the reason is not that documentation does not matter. It is that writing a paragraph about each endpoint feels like a distraction from the actual work of building and testing the API.

Voice closes that gap. Describing what an endpoint does, what parameters it accepts, and what errors it returns takes 30 seconds of speaking. Typing the same information takes 3-4 minutes. At 30 seconds per endpoint, documenting a 20-endpoint collection becomes practical instead of aspirational.

1. Open Postman desktop app (or the web version in your browser).
2. Select a request from your collection in the left sidebar.
3. Click the description area below the request name, or click the "Documentation" icon in the right panel.
4. Click into the text field where you want documentation.
5. Press ⌃+⌥+R (Mac) or Ctrl+Alt+R (Windows/Linux) to start recording.
6. Speak your API explanation: what the endpoint does, required and optional parameters, expected responses, and common error cases.
7. Press the hotkey again. AICHE transcribes and inserts the text.

Heads-up: Postman descriptions support markdown. After dictating, add code blocks (for JSON examples), tables (for parameter lists), and links manually. The prose content is already there; you are adding structure.

Endpoint Documentation

Request Descriptions

Every Postman request has a description field. Click into it and dictate what the endpoint does, when to call it, and what to expect back. Be specific: describe the authentication requirements, rate limits, pagination behavior, and response format.

For example, dictate "this endpoint retrieves a paginated list of user orders. Requires a valid Bearer token in the Authorization header. Accepts page and limit query parameters, where page defaults to 1 and limit defaults to 20 with a maximum of 100. Returns a JSON object with a data array of order objects and a meta object containing total count, current page, and total pages. Orders are sorted by creation date descending. Returns 401 if the token is missing or expired, and 403 if the authenticated user does not have permission to view orders for the specified user ID."

That description takes 25 seconds to speak and covers everything another developer needs to use the endpoint correctly.

Parameter Explanations

Postman lets you document individual query parameters, headers, and body fields. Click into the description column next to any parameter and dictate what it means. This is where most API documentation fails - parameters are listed but not explained. Say "the status filter accepts a comma-separated list of order statuses: pending, processing, shipped, delivered, cancelled. If omitted, returns all statuses. Invalid status values are silently ignored rather than returning an error."

Collection-Level Documentation

Collection Overview

Every Postman collection has a description at the top level. Click the three dots on your collection name, select Edit, and click into the description. Dictate the big picture: what this API does, how authentication works across all endpoints, what the base URL structure is, and what common patterns (like error response format) apply to every request.

This overview is what new team members read first. It should answer "what is this API and how do I start using it?" without requiring them to read every individual request.

Folder Descriptions

If your collection uses folders to organize endpoints (Users, Orders, Payments, Admin), each folder can have a description. Dictate what the group of endpoints covers, any shared authentication or permission requirements, and the typical usage flow. Say "the Orders folder contains endpoints for creating, retrieving, updating, and cancelling orders. All endpoints require authentication and the orders.read or orders.write scope. The typical flow is: create an order with POST /orders, then retrieve status with GET /orders/id, and cancel if needed with DELETE /orders/id."

Test Case Comments

Documenting Test Scripts

Postman's test scripts (in the Tests tab) often contain assertions and setup logic that is not self-explanatory. Click into the test script editor, position cursor above a test block, and dictate what the test verifies and why it matters.

For pre-request scripts that set up variables, dictate what each variable represents and where it comes from. This is especially useful for collections that use chained requests, where a token from one response feeds into the next request's headers. The logic is hard to follow without comments, and commenting test scripts is something almost nobody does.

Environment Variable Documentation

Postman environments (Dev, Staging, Production) contain variables that drive your requests. Open the environment editor, and for each variable, dictate its purpose in the description field. Explain what valid values look like, where to get the value (from a team wiki, a deployment script, or another API call), and what happens if the value is wrong.

API Changelog Entries

When your API changes between versions, maintain a changelog. Create a request in your collection called "Changelog" or keep a separate markdown document. After each API change, press your hotkey and dictate what changed: new endpoints, deprecated fields, modified response formats, updated rate limits, and any breaking changes that require client updates.

API changelogs that get updated consistently build trust with API consumers. They know what changed and when, which makes integration maintenance predictable.

Postman-Specific Tips

• Published documentation. Postman can generate a public documentation site from your collection descriptions. Everything you dictate becomes part of that published API reference. Higher quality dictated docs mean a better public-facing API site.
• Team workspaces. In team workspaces, your documentation is visible to everyone on the team. Dictating thorough descriptions raises the documentation baseline for the entire team's collections.
• Mock servers. Postman's mock servers use example responses you define. Dictate descriptions for each example explaining what scenario it represents (success case, validation error, rate limit exceeded) so mock consumers understand what they are testing against.
• Collection runner notes. When using Postman's collection runner for integration tests, add descriptions to each request explaining the expected test flow. This turns your collection into a runnable integration test with built-in documentation.

The pro-tip: When documenting collections, dictate authentication setup and common error scenarios once at the collection level, then reference them in individual requests. Say "authentication follows the pattern described in the collection overview" instead of repeating the same explanation on every endpoint.

Result: API collections with complete endpoint descriptions, parameter explanations, and error documentation. Published API docs that developers can actually use without messaging you for clarification. The documentation quality that Postman's tooling was designed for, actually achieved.

Do this now: Open a Postman collection, click into the description of your most-used request, press your hotkey, and dictate what the endpoint does, what parameters it needs, and what it returns.