165 lines
3.4 KiB
Markdown
165 lines
3.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
localapi-docs validate petstore.json
|
|
localapi-docs validate petstore.yaml --json
|
|
```
|
|
|
|
### Search Endpoints
|
|
|
|
Search for endpoints in your API specification:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
localapi-docs generate api-spec.yaml --format html --open
|
|
```
|
|
|
|
### Serve on Custom Port
|
|
|
|
```bash
|
|
localapi-docs serve api-spec.json --port 3000
|
|
```
|
|
|
|
### Validate with JSON Output
|
|
|
|
```bash
|
|
localapi-docs validate api-spec.json --json
|
|
```
|
|
|
|
### Search and Get JSON Results
|
|
|
|
```bash
|
|
localapi-docs search api-spec.json users --json
|
|
```
|
|
|
|
## Configuration
|
|
|
|
No configuration files required. All options are passed via CLI arguments.
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# 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
|