postman-claude-code-plugin/commands/codegen.md

description, allowed-tools

description	allowed-tools
Generate typed client code from Postman collections. Reads your private APIs and writes production-ready code.	Bash, Read, Write, Glob, Grep, mcp__postman__*

Generate Client Code

Generate typed client code from Postman collections. Reads your private API definitions and writes production-ready code that matches your project's conventions.

Prerequisites

The Postman MCP Server must be connected. If MCP tools aren't available, tell the user: "Run /postman:setup to configure the Postman MCP Server."

Workflow

Step 1: Find the API

1. Call searchPostmanElementsInPrivateNetwork with the API name to find it in the organization's private network.
2. If no results, call getWorkspaces to get the user's workspace ID. If multiple workspaces exist, ask which to use. Then use getCollections with the workspace parameter and name filter if the user specified an API name.
3. If still no results, fall back to searchPostmanElementsInPublicNetwork to search the public Postman network.
4. If multiple matches, list them and ask which one.
5. Call getCollection to get the full collection.
6. Call getSpecDefinition if a linked spec exists (richer type info).

Step 2: Understand the API Shape

For the target collection:

1. Call getCollectionFolder for each folder to understand resource grouping
2. Call getCollectionRequest for each relevant endpoint to get:
   • HTTP method and URL
   • Request headers and auth
   • Request body schema
   • Path and query parameters
3. Call getCollectionResponse for each request to get:
   • Response status codes
   • Response body shapes (for typing)
   • Error response formats
4. Call getEnvironment to understand base URLs and variables
5. Call getCodeGenerationInstructions for any Postman-specific codegen guidance

Step 3: Detect Project Language

If the user doesn't specify a language, detect from the project:

• package.json or tsconfig.json → TypeScript/JavaScript
• requirements.txt or pyproject.toml → Python
• go.mod → Go
• Cargo.toml → Rust
• pom.xml or build.gradle → Java
• Gemfile → Ruby

Step 4: Generate Code

Generate a typed client class or module with:

• Method per endpoint with proper parameters
• Request/response types from collection schemas
• Authentication handling (from collection auth config)
• Error handling based on documented error responses
• Environment-based configuration (base URL from env vars)
• Pagination support if the API uses it

Code conventions:

• Match the project's existing style (imports, formatting, naming)
• Include JSDoc/docstrings from collection descriptions
• Use the project's HTTP library if one exists (axios, fetch, requests, etc.)
• Write to a sensible file path (e.g., src/clients/<api-name>.ts)

Step 5: Present

Generated: src/clients/users-api.ts

  Endpoints covered:
    GET    /users         → getUsers(filters)
    GET    /users/{id}    → getUser(id)
    POST   /users         → createUser(data)
    PUT    /users/{id}    → updateUser(id, data)
    DELETE /users/{id}    → deleteUser(id)

  Types generated:
    User, CreateUserRequest, UpdateUserRequest,
    UserListResponse, ApiError

  Auth: Bearer token (from USERS_API_TOKEN env var)
  Base URL: from USERS_API_BASE_URL env var

Error Handling

• MCP not configured: "Run /postman:setup to configure the Postman MCP Server."
• Collection not found: "No collection matching that name. Run /postman:search to find available APIs."
• 401 Unauthorized: "Your Postman API key was rejected. Generate a new one at https://postman.postman.co/settings/me/api-keys and run /postman:setup."
• Empty collection: "This collection has no requests. Add endpoints in Postman or use /postman:sync to push a spec."
• Language not detected: Ask the user what language to generate.