120 lines
2.7 KiB
Markdown
120 lines
2.7 KiB
Markdown
# LocalAPI Docs
|
|
|
|
A CLI tool that generates local, privacy-focused API documentation server from OpenAPI/Swagger specs. Features include interactive endpoint testing with mock requests, automatic request/response examples, search functionality, and multiple output formats (HTML, Markdown, JSON). Runs entirely locally with no data leaving the machine.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pip install localapi-docs
|
|
```
|
|
|
|
Or from source:
|
|
|
|
```bash
|
|
git clone https://github.com/yourusername/localapi-docs.git
|
|
cd localapi-docs
|
|
pip install -e .
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Serve Interactive HTML Documentation
|
|
|
|
```bash
|
|
localapi-docs serve openapi.yaml
|
|
```
|
|
|
|
This starts a local web server at `http://127.0.0.1:8080` with interactive API documentation. You can test endpoints directly in the browser.
|
|
|
|
### Generate Static Documentation
|
|
|
|
Generate HTML documentation:
|
|
```bash
|
|
localapi-docs generate openapi.yaml -o docs.html
|
|
```
|
|
|
|
Generate Markdown documentation:
|
|
```bash
|
|
localapi-docs generate openapi.yaml -o docs.md --format markdown
|
|
```
|
|
|
|
Generate JSON documentation:
|
|
```bash
|
|
localapi-docs generate openapi.yaml -o docs.json --format json
|
|
```
|
|
|
|
### Validate OpenAPI Specification
|
|
|
|
```bash
|
|
localapi-docs validate openapi.yaml
|
|
```
|
|
|
|
### Search Endpoints
|
|
|
|
```bash
|
|
localapi-docs search openapi.yaml "users list"
|
|
```
|
|
|
|
## Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `serve` | Serve interactive HTML documentation locally |
|
|
| `generate` | Generate documentation in HTML, Markdown, or JSON format |
|
|
| `validate` | Validate an OpenAPI specification file |
|
|
| `search` | Search for endpoints in an OpenAPI specification |
|
|
|
|
### Serve Options
|
|
|
|
| Option | Default | Description |
|
|
|--------|---------|-------------|
|
|
| `--host` | `127.0.0.1` | Host to bind the server to |
|
|
| `--port` | `8080` | Port to bind the server to |
|
|
|
|
### Generate Options
|
|
|
|
| Option | Default | Description |
|
|
|--------|---------|-------------|
|
|
| `--output, -o` | Auto-generated | Output file path |
|
|
| `--format` | `html` | Output format (html, markdown, json) |
|
|
| `--template` | None | Custom template file path |
|
|
|
|
## Features
|
|
|
|
- **Privacy-First**: All processing happens locally. No data leaves your machine.
|
|
- **Interactive Testing**: Test API endpoints directly from the HTML documentation.
|
|
- **Multiple Formats**: Generate HTML, Markdown, or JSON documentation.
|
|
- **Search**: Full-text search across endpoints, tags, and descriptions.
|
|
- **Automatic Examples**: Auto-generate request/response examples from schemas.
|
|
- **OpenAPI 3.0/3.1**: Full support for modern OpenAPI specifications.
|
|
|
|
## Development
|
|
|
|
Install development dependencies:
|
|
|
|
```bash
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
Run tests:
|
|
|
|
```bash
|
|
pytest tests/ -v
|
|
```
|
|
|
|
Run linter:
|
|
|
|
```bash
|
|
ruff check src/ tests/
|
|
```
|
|
|
|
Run type checker:
|
|
|
|
```bash
|
|
mypy src/ --ignore-missing-imports
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|