localapi-docs/README.md

LocalAPI Docs

A CLI tool that generates local, privacy-focused API documentation server from OpenAPI/Swagger specs with interactive endpoint testing, automatic examples, and multiple output formats running entirely locally.

Features

• Local Documentation Server - Serve interactive HTML docs locally with no external dependencies
• Multiple Output Formats - Generate HTML, Markdown, or JSON documentation
• Automatic Example Generation - Creates realistic request/response examples from your schemas
• Full-Text Search - Search across endpoints, tags, and descriptions
• Spec Validation - Validate OpenAPI specs with detailed error messages
• Privacy-Focused - Everything runs locally, no data leaves your machine

Installation

# Install from source
pip install -e .

# Or install with dev dependencies
pip install -e .[dev]

Usage

Serve Interactive Documentation

Start a local web server with interactive API documentation:

localapi-docs serve petstore.json
localapi-docs serve petstore.yaml --host 0.0.0.0 --port 8080

The server will automatically open in your default browser.

Generate Static Documentation

Generate documentation in various formats:

# Generate HTML documentation
localapi-docs generate petstore.json --format html

# Generate Markdown documentation
localapi-docs generate petstore.json --format markdown

# Generate JSON documentation
localapi-docs generate petstore.json --format json

# Generate all formats
localapi-docs generate petstore.json --format all

Validate OpenAPI Specs

Validate your OpenAPI specification file:

localapi-docs validate petstore.json
localapi-docs validate petstore.yaml --json

Search Endpoints

Search for endpoints in your API specification:

localapi-docs search petstore.json users
localapi-docs search petstore.json "get pet" --limit 10
localapi-docs search petstore.json users --json

Commands

serve

Start an interactive HTML documentation server.

Options:

• --host, -h: Host to bind to (default: 127.0.0.1)
• --port, -p: Port to serve on (default: 8080)
• --no-browser: Don't open browser automatically

generate

Generate static documentation in various formats.

Options:

• --output, -o: Output file or directory
• --format, -f: Output format (html, markdown, json, all)
• --open: Open the generated file in browser

validate

Validate an OpenAPI specification file.

Options:

• --json: Output as JSON

search

Search for endpoints in an OpenAPI specification.

Options:

• --limit, -l: Maximum results (default: 10)
• --json: Output as JSON

Examples

Generate and Open HTML Docs

localapi-docs generate api-spec.yaml --format html --open

Serve on Custom Port

localapi-docs serve api-spec.json --port 3000

Validate with JSON Output

localapi-docs validate api-spec.json --json

Search and Get JSON Results

localapi-docs search api-spec.json users --json

Configuration

No configuration files required. All options are passed via CLI arguments.

Development

# Install development dependencies
pip install -e .[dev]

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src --cov-report=term-missing

Supported OpenAPI Versions

• OpenAPI 3.0.x
• OpenAPI 3.1.x

Input Formats

• JSON (.json)
• YAML (.yaml, .yml)

License

MIT