docs

API Documentation

Analyze, improve, and publish API documentation from OpenAPI specs and Postman collections.

Prerequisites

The Postman MCP Server must be connected for Postman operations. Local spec analysis works without MCP. If needed, tell the user: "Run /postman:setup to configure the Postman MCP Server."

Workflow

Step 1: Find the Source

Call getWorkspaces to get the user's workspace ID. If multiple workspaces exist, ask which to use.

Check for API definitions in this order:

Local specs:

• Search for **/openapi.{json,yaml,yml}, **/swagger.{json,yaml,yml}

Postman specs:

• Call getAllSpecs with the workspace ID to find specs in Postman
• Call getSpecDefinition to pull the full spec

Postman collections:

• Call getCollections with the workspace parameter
• Call getCollection for full detail

Step 2: Analyze Documentation Completeness

Read the spec/collection and assess:

Documentation Coverage: 60%
  Endpoints with descriptions:     8/15
  Parameters with descriptions:    22/45
  Endpoints with examples:         3/15
  Error responses documented:      2/15
  Authentication documented:       Yes
  Rate limits documented:          No

Step 3: Generate or Improve

Sparse spec: Generate documentation for each endpoint:

• Operation summary and description
• Parameter table (name, type, required, description)
• Request body schema with examples
• Response schemas with examples for each status code
• Error response documentation
• Authentication requirements per endpoint

Partial spec: Fill the gaps:

• Add missing descriptions (infer from naming and schemas)
• Generate realistic examples from schemas
• Add error responses
• Document authentication and rate limits

Step 4: Apply Changes

Ask the user which output they want:

1. Update the spec file - Write improved docs back into the OpenAPI spec
2. Update in Postman - Use updateCollectionRequest to add descriptions and examples to each request
3. Publish public docs - Call publishDocumentation with:
   • collectionId: the collection's unique ID
   • customColor and customization for branding
   • Returns a public URL for the docs
   • To unpublish later, call unpublishDocumentation with the collection ID
4. Generate markdown - Create a docs/api-reference.md file for the project