api-docs-gen

A Claude Code plugin that analyzes your backend codebase and generates API documentation automatically.

Output Formats

• OpenAPI 3.0 (openapi.yaml) — Industry-standard API specification
• Postman Collection (postman-collection.json) — Import directly into Postman
• Swagger UI (swagger-ui.html) — Interactive API docs in your browser

Supported Frameworks

Language	Frameworks
Node.js	Express, NestJS, Fastify, Koa, Hapi
Python	FastAPI, Django REST Framework, Flask
Go	Gin, Echo, Chi, Gorilla Mux, Fiber
Java/Kotlin	Spring Boot
Ruby	Rails

Installation

Local (development)

claude --plugin-dir /path/to/api-docs-gen

From marketplace (coming soon)

claude plugin install api-docs-gen

Usage

Inside Claude Code, run:

/api-docs-gen:generate

With arguments

/api-docs-gen:generate --format openapi --output ./api-spec --base-url https://api.example.com

Available flags

Flag	Values	Default	Description
--format	openapi, postman, swagger, all	all	Which format(s) to generate
--output	directory path	./docs/	Where to write the generated files
--base-url	URL	http://localhost:3000	Base server URL for the API

Configuration File

Create .api-docs.json in your project root for persistent settings:

{
  "format": "all",
  "output": "./docs",
  "baseUrl": "https://api.example.com",
  "title": "My API",
  "version": "1.0.0",
  "auth": {
    "type": "bearer",
    "description": "JWT token from /auth/login"
  },
  "ignore": [
    "**/test/**",
    "**/spec/**",
    "internal/**"
  ],
  "tags": {
    "users": "User management endpoints",
    "orders": "Order processing"
  }
}

All fields are optional. CLI arguments override config file values.

Config fields

Field	Type	Description
format	string	Output format: openapi, postman, swagger, or all
output	string	Output directory path
baseUrl	string	Base URL for the API server
title	string	API title (falls back to package name)
version	string	API version (falls back to package version)
auth	object	Default auth scheme (type + description)
ignore	string[]	Glob patterns for files/dirs to skip
tags	object	Tag name → description mapping for grouping endpoints

How It Works

1. Detects your framework — reads package.json, requirements.txt, go.mod, etc.
2. Discovers routes — uses framework-specific patterns to find all API endpoints
3. Extracts schemas — reads validation libraries (Zod, Joi, Pydantic, class-validator), DTOs, type annotations, and docstrings
4. Generates docs — produces valid OpenAPI 3.0 YAML, Postman Collection JSON, and Swagger UI HTML

After Generation

# Validate the OpenAPI spec
npx @redocly/cli lint docs/openapi.yaml

# Preview Swagger UI (needs local server for YAML loading)
npx serve docs

# Import Postman collection
# Open Postman → Import → Upload docs/postman-collection.json

License

MIT