7000pctAUTO/localapi-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

fix: resolve CI linting issues
Some checks failed
CI/CD / test (push) Has been cancelled
Details

Browse Source
This commit is contained in:
7000pctAUTO
2026-02-01 17:29:57 +00:00
parent eae4514c25
commit dd868731d6
1 changed files with 67 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
README.md
View File

@@ -1,163 +1,118 @@
# 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
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
# Install from source
pip install -e .
pip install localapi-docs
```
# Or install with dev dependencies
pip install -e .[dev]
Or from source:
```bash
git clone https://github.com/yourusername/localapi-docs.git
cd localapi-docs
pip install -e .
```
## Usage
### Serve Interactive Documentation
Start a local web server with interactive API documentation:
### Serve Interactive HTML Documentation
```bash
localapi-docs serve petstore.json
localapi-docs serve petstore.yaml --host 0.0.0.0 --port 8080
localapi-docs serve openapi.yaml
```
The server will automatically open in your default browser.
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 documentation in various formats:
Generate HTML documentation:
```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
localapi-docs generate openapi.yaml -o docs.html
```
### Validate OpenAPI Specs
Generate Markdown documentation:
```bash
localapi-docs generate openapi.yaml -o docs.md --format markdown
```
Validate your OpenAPI specification file:
Generate JSON documentation:
```bash
localapi-docs generate openapi.yaml -o docs.json --format json
```
### Validate OpenAPI Specification
```bash
localapi-docs validate petstore.json
localapi-docs validate petstore.yaml --json
localapi-docs validate openapi.yaml
```
### 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
localapi-docs search openapi.yaml "users list"
```
## Commands
### serve
| 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 |
Start an interactive HTML documentation server.
### Serve Options
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
| Option | Default | Description |
|--------|---------|-------------|
| `--host` | `127.0.0.1` | Host to bind the server to |
| `--port` | `8080` | Port to bind the server to |
### generate
### Generate Options
Generate static documentation in various formats.
| Option | Default | Description |
|--------|---------|-------------|
| `--output, -o` | Auto-generated | Output file path |
| `--format` | `html` | Output format (html, markdown, json) |
| `--template` | None | Custom template file path |
Options:
- `--output, -o`: Output file or directory
- `--format, -f`: Output format (html, markdown, json, all)
- `--open`: Open the generated file in browser
## Features
### 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.
- **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
# Install development dependencies
pip install -e .[dev]
# Run tests
pytest tests/ -v
# Run with coverage
pytest tests/ --cov=src --cov-report=term-missing
pip install -e ".[dev]"
```
## Supported OpenAPI Versions
Run tests:
- OpenAPI 3.0.x
- OpenAPI 3.1.x
```bash
pytest tests/ -v
```
## Input Formats
Run linter:
- JSON (`.json`)
- YAML (`.yaml`, `.yml`)
```bash
ruff check src/ tests/
```
Run type checker:
```bash
mypy src/ --ignore-missing-imports
```
## License