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 # 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. 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.
## 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 ## Installation
```bash ```bash
# Install from source pip install localapi-docs
pip install -e . ```
# Or install with dev dependencies Or from source:
pip install -e .[dev]
```bash
git clone https://github.com/yourusername/localapi-docs.git
cd localapi-docs
pip install -e .
``` ```
## Usage ## Usage
### Serve Interactive Documentation ### Serve Interactive HTML Documentation
Start a local web server with interactive API documentation:
```bash ```bash
localapi-docs serve petstore.json localapi-docs serve openapi.yaml
localapi-docs serve petstore.yaml --host 0.0.0.0 --port 8080
``` ```
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 Static Documentation
Generate documentation in various formats: Generate HTML documentation:
```bash ```bash
# Generate HTML documentation localapi-docs generate openapi.yaml -o docs.html
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 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 ```bash
localapi-docs validate petstore.json localapi-docs validate openapi.yaml
localapi-docs validate petstore.yaml --json
``` ```
### Search Endpoints ### Search Endpoints
Search for endpoints in your API specification:
```bash ```bash
localapi-docs search petstore.json users localapi-docs search openapi.yaml "users list"
localapi-docs search petstore.json "get pet" --limit 10
localapi-docs search petstore.json users --json
``` ```
## Commands ## 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: | Option | Default | Description |
- `--host, -h`: Host to bind to (default: 127.0.0.1) |--------|---------|-------------|
- `--port, -p`: Port to serve on (default: 8080) | `--host` | `127.0.0.1` | Host to bind the server to |
- `--no-browser`: Don't open browser automatically | `--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: ## Features
- `--output, -o`: Output file or directory
- `--format, -f`: Output format (html, markdown, json, all)
- `--open`: Open the generated file in browser
### validate - **Privacy-First**: All processing happens locally. No data leaves your machine.
- **Interactive Testing**: Test API endpoints directly from the HTML documentation.
Validate an OpenAPI specification file. - **Multiple Formats**: Generate HTML, Markdown, or JSON documentation.
- **Search**: Full-text search across endpoints, tags, and descriptions.
Options: - **Automatic Examples**: Auto-generate request/response examples from schemas.
- `--json`: Output as JSON - **OpenAPI 3.0/3.1**: Full support for modern OpenAPI specifications.
### 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 ## Development
Install development dependencies:
```bash ```bash
# Install development dependencies pip install -e ".[dev]"
pip install -e .[dev]
# Run tests
pytest tests/ -v
# Run with coverage
pytest tests/ --cov=src --cov-report=term-missing
``` ```
## Supported OpenAPI Versions Run tests:
- OpenAPI 3.0.x ```bash
- OpenAPI 3.1.x pytest tests/ -v
```
## Input Formats Run linter:
- JSON (`.json`) ```bash
- YAML (`.yaml`, `.yml`) ruff check src/ tests/
```
Run type checker:
```bash
mypy src/ --ignore-missing-imports
```
## License ## License