Power Generate Api Documentation

Auto-generate comprehensive API reference documentation from code annotations, route definitions, and type schemas.

When to Use This Command

Run this command when you need to:

• Generate OpenAPI/Swagger specification files from annotated API source code
• Create interactive API documentation with try-it-out functionality and example requests
• Produce API reference docs with request/response schemas, authentication guides, and error codes

Consider alternatives when:

• You are designing an API that does not exist yet and need a spec-first approach
• Your API already has a hand-maintained OpenAPI spec and you only need a renderer

Quick Start

Configuration

Copy
name: power-generate-api-documentation
type: command
category: documentation

Example Invocation

Copy
claude command:run power-generate-api-documentation --framework express --output openapi

Example Output

API Source Scan:
  Framework: Express.js + TypeScript
  Routes found: 42 endpoints across 8 route files
  Annotations: 38/42 endpoints have JSDoc comments
  Schemas: 24 request/response interfaces detected

Generated Documentation:
  [+] docs/openapi.yaml (OpenAPI 3.1 specification)
  [+] docs/api-reference.md (42 endpoints documented)
  [+] docs/authentication.md (Bearer token + API key flows)
  [+] docs/error-codes.md (18 error codes with descriptions)
  [+] docs/examples/ (42 curl examples, 42 JavaScript examples)

Validation:
  [OK] OpenAPI spec validates against 3.1 schema
  [OK] All examples return expected status codes
  [WARN] 4 endpoints missing response schema annotations

Interactive docs: npx redocly preview docs/openapi.yaml

Core Concepts

API Documentation Overview

Aspect	Details
Route Extraction	Scans Express, Fastify, Django, Flask, or Go route definitions
Schema Generation	Converts TypeScript interfaces and Zod schemas to JSON Schema
Auth Documentation	Detects middleware patterns to document authentication flows
Example Generation	Creates curl, JavaScript, and Python request examples per endpoint
Spec Validation	Validates generated OpenAPI spec against the official JSON Schema

Generation Pipeline Workflow

  API Source Code
       |
       v
  +-------------------+
  | Scan Routes       |---> GET /users, POST /auth, etc.
  +-------------------+
       |
       v
  +-------------------+
  | Extract Schemas   |---> Request body, response, params
  +-------------------+
       |
       v
  +-------------------+
  | Parse Annotations |---> JSDoc, decorators, comments
  +-------------------+
       |
       v
  +-------------------+
  | Generate Spec     |---> OpenAPI 3.1 YAML/JSON
  +-------------------+
       |
       v
  +-------------------+
  | Create Examples   |---> curl, JS, Python snippets
  +-------------------+
       |
       v
  +-------------------+
  | Validate + Render |---> Spec check, Redoc/Swagger UI
  +-------------------+

Configuration

Parameter	Type	Default	Description
framework	string	auto-detect	API framework: express, fastify, django, flask, gin
output	string	openapi	Output format: openapi, markdown, html, or all
spec_version	string	3.1	OpenAPI specification version: 3.0 or 3.1
include_examples	boolean	true	Generate request/response examples for each endpoint
base_url	string	http://localhost:3000	Base URL used in generated examples and spec servers

Best Practices

1. Annotate Routes Consistently - Use JSDoc or framework-specific decorators on every route handler. The generator can only document what it can find; unannotated routes produce incomplete specs.

2. Define Response Schemas Explicitly - Do not rely on the generator to infer response shapes from implementation code. Explicit response type definitions produce accurate documentation and serve as a contract.

3. Include Error Responses - Document error status codes (400, 401, 403, 404, 500) with their response shapes. API consumers need to handle errors, and undocumented error responses lead to fragile client code.

4. Version Your API Documentation - Tag documentation with the API version it describes. When the API evolves, consumers need to reference the documentation version that matches the API version they are using.

5. Validate Spec in CI - Run OpenAPI spec validation in your CI pipeline to catch schema errors before they reach published documentation. A malformed spec breaks documentation renderers and code generators.

Common Issues

1. Routes Not Detected - Dynamic route registration or middleware-based routing is not captured by static analysis. Add explicit route annotations or maintain a route manifest file that the generator can parse.

2. TypeScript Types Not Resolved - Generic types and utility types (Pick, Omit, Partial) are not expanded in the generated schemas. Use concrete interfaces for API request/response types rather than composed utility types.

3. Generated Spec Fails Validation - Circular references or missing schema definitions cause validation errors. Break circular type dependencies and ensure all referenced schemas are defined in the spec components section.