Better Swagger

Better Swagger converts Swagger/OpenAPI docs into LLM-friendly markdown. It flattens structures, adds search indexes, and removes noise to help AI Agents understand APIs accurately.

Features

• LLM-Optimized: Recursively expands $ref and nested structures for self-contained context.
• Searchable: Generates natural language indexes.
• Efficient: Outputs TSV code blocks for deterministic parsing and lower token overhead.

Quick Start

npx better-swagger <swaggerUrl> [options]
npx better-swagger ui <swaggerUrl>

Options

Option	Description
--output, -o	Output directory for Markdown files.
--tags, -t	Generate only specified tags (comma-separated).
--all, -a	Generate all tags without prompting.

Example

# Generate api docs
npx better-swagger https://petstore3.swagger.io/api/v3/openapi.json

# Custom output directory
npx better-swagger https://petstore3.swagger.io/api/v3/openapi.json --output ./docs/api

# Generate only selected tags
npx better-swagger https://petstore3.swagger.io/api/v3/openapi.json --tags pet,user

# Generate all tags without prompt
npx better-swagger https://petstore3.swagger.io/api/v3/openapi.json --all

# UI
npx better-swagger ui https://petstore3.swagger.io/api/v3/openapi.json