From dd868731d69e83c22d6fa3b89c2d6a76c8486286 Mon Sep 17 00:00:00 2001 From: 7000pctAUTO Date: Sun, 1 Feb 2026 17:29:57 +0000 Subject: [PATCH] fix: resolve CI linting issues --- README.md | 179 ++++++++++++++++++++---------------------------------- 1 file changed, 67 insertions(+), 112 deletions(-) diff --git a/README.md b/README.md index da2ff24..7319d8f 100644 --- a/README.md +++ b/README.md @@ -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