swagger2drawio 1.0.0__tar.gz

swagger2drawio-1.0.0/.gitignore

@@ -0,0 +1,67 @@
+# ── Python ────────────────────────────────────────────────────
+__pycache__/
+*.py[oc]
+*.pyd
+*.pyo
+build/
+dist/
+wheels/
+*.egg-info/
+*.egg
+MANIFEST
+
+# ── Virtual environments ──────────────────────────────────────
+.venv/
+venv/
+env/
+.env/
+
+# ── UV ────────────────────────────────────────────────────────
+.python-version
+uv.lock
+
+# ── Distribution / packaging ──────────────────────────────────
+*.tar.gz
+*.whl
+site/
+
+# ── Testing ───────────────────────────────────────────────────
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.lcov
+.tox/
+.nox/
+
+# ── Type checking ─────────────────────────────────────────────
+.mypy_cache/
+.pyright/
+.ruff_cache/
+
+# ── Generated Draw.io output ──────────────────────────────────
+# Keep example specs but ignore generated diagrams
+examples/output/
+
+# ── IDEs & editors ────────────────────────────────────────────
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# ── Environment variables ─────────────────────────────────────
+.env
+.envrc
+*.env.local
+
+# ── Logs ──────────────────────────────────────────────────────
+*.log
+logs/
+
+# ── OS ────────────────────────────────────────────────────────
+.DS_Store
+desktop.ini

swagger2drawio-1.0.0/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] — 2026-05-17
+
+First stable release. The CLI surface (`generate`, `validate`, `diff`,
+`init`, `themes list / show`), the typed exception hierarchy + exit
+codes, the bundled themes, and the `swagger2drawio.layouts` entry-point
+group are all considered API stable.
+
+### Added — Phase 5 (Code Quality)
+
+- `SpecParser` `Protocol` and `get_parser(raw_dict)` factory for parser
+  polymorphism (`swagger2drawio/parser/base.py`).
+- `OpenAPIParser.parse_dict()` + `OpenAPIParser.from_dict_factory()` so
+  callers with an in-memory spec can skip the I/O layer.
+- `LayoutStrategy` Protocol with two built-in strategies
+  (`HierarchicalBFSLayout`, `GridLayout`) and entry-point discovery
+  through the `swagger2drawio.layouts` group.
+- `--layout` CLI flag and `build_endpoint_graph(layout=...)` parameter.
+
+### Changed — Phase 5
+
+- All diff dataclasses now use `slots=True`.
+- `Parameter.__post_init__` validates `in` against the OpenAPI
+  location set; `MethodDetail.__post_init__` validates `verb` against
+  the HTTP-method set.
+- `mypy --strict` now passes on the whole package, not just the
+  parser / layout subpackages.
+
+### Added — Phase 4 (CLI & UX)
+
+- Bundled themes: `light`, `dark`, `pastel`, `high-contrast` under
+  `swagger2drawio/themes/*.yaml`.
+- `--theme <name>` flag on `generate`.
+- `themes list` and `themes show <name>` subcommands.
+- `init` subcommand that scaffolds a `.swagger2drawio.yaml` in CWD.
+- Config discovery order: `--config` → `--theme` →
+  `./.swagger2drawio.yaml` → `$XDG_CONFIG_HOME/swagger2drawio/config.yaml`
+  → built-in defaults (deep-merged).
+- `rich.progress` spinner + bar during `generate`, with a final summary
+  line: `<file> written (X.X KB) — N path(s), M method(s), K schema(s)`.
+- Shell completion via Typer's `--install-completion` / `--show-completion`.
+
+### Added — Phase 3 (Feature Expansion)
+
+- Richer endpoint rendering: parameters, request-body and response-ref
+  links, deprecated flag, request/response refs inline in the method
+  label, height auto-scales with content.
+- Tag-based grouping (`--group-by tag|path|auto`).
+- Schema composition: `allOf` / `oneOf` / `anyOf` / `discriminator`
+  edges with distinct styles; enum types rendered as `«enum»` nodes.
+- Security legend (`securitySchemes` → standalone node) and an info
+  banner on the root with title / version / description / server URLs.
+- **Diff mode** — new `swagger2drawio diff OLD NEW` subcommand
+  producing a three-page (`Summary` / `Endpoints` / `Schemas`)
+  side-by-side `.drawio` with green/red/yellow overlays and dashed
+  connectors between changed pairs.
+
+### Added — Phase 2 (Robustness)
+
+- Typed exception hierarchy (`Swagger2DrawioError` and six subclasses)
+  with a stable per-category exit code map (`EXIT_CODE`, codes 1–7).
+- `openapi-spec-validator` integration. New `validate` subcommand and
+  a `--no-validate` flag on `generate` (validation is on by default).
+- `RefResolver` inlines external file / remote URL `$ref`s into
+  `components.schemas` with cycle safety and per-document caching.
+- Network options on `generate`: `--timeout`, `--header / -H`
+  (repeatable), `--insecure`.
+- Rich-based logging: `--verbose / -v` (count), `--quiet / -q`,
+  `--log-file <path>`.
+
+### Changed — Phase 2
+
+- **Breaking** — `--version` no longer has the `-v` short alias.
+  `-v` is now `--verbose` (count). `--version` still works.
+
+### Added — Phase 1 (Foundations)
+
+- Modern packaging via `hatchling` with dynamic version from
+  `swagger2drawio/__init__.py`.
+- Test infrastructure: 96.7% coverage on parser/layout/renderer.
+- `ruff` + `mypy` + `pre-commit` configuration.
+- GitHub Actions CI (Python 3.10 × 3 OS matrix) and trusted-publishing
+  release workflow.
+
+## [0.1.0] — 2026-02-20
+
+Initial public release. Single `generate` command. OAS 3 + Swagger 2
+support. Two-page output (Endpoints Map, Schema Map).

swagger2drawio-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abhishek Kumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

swagger2drawio-1.0.0/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: swagger2drawio
+Version: 1.0.0
+Summary: Generate structured Draw.io diagrams from OpenAPI 3.x / Swagger 2.0 specs.
+Project-URL: Homepage, https://github.com/Abhishek-k03/swagger2drawio
+Project-URL: Repository, https://github.com/Abhishek-k03/swagger2drawio
+Project-URL: Issues, https://github.com/Abhishek-k03/swagger2drawio/issues
+Project-URL: Changelog, https://github.com/Abhishek-k03/swagger2drawio/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://Abhishek-k03.github.io/swagger2drawio/
+Author-email: Abhishek Kumar <thehypnoticsilence@gmail.com>
+Maintainer-email: Abhishek Kumar <thehypnoticsilence@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: api,diagram,documentation,drawio,openapi,swagger,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: drawpyo>=0.2.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: openapi-spec-validator>=0.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pre-commit>=3.8; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs-typer>=0.0.3; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=5; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# swagger2drawio
+
+[![CI](https://github.com/Abhishek-k03/swagger2drawio/actions/workflows/ci.yml/badge.svg)](https://github.com/Abhishek-k03/swagger2drawio/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/swagger2drawio.svg)](https://pypi.org/project/swagger2drawio/)
+[![Python versions](https://img.shields.io/pypi/pyversions/swagger2drawio.svg)](https://pypi.org/project/swagger2drawio/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> Turn an OpenAPI 3.x / Swagger 2.0 spec into a clean, structured
+> [draw.io](https://app.diagrams.net/) diagram. Local files, remote
+> URLs, multi-file `$ref`s — all in one command.
+
+```text
+$ swagger2drawio generate -i petstore.yaml -o api.drawio
+✔  api.drawio written (12.4 KB) — 8 path(s), 14 method(s), 6 schema(s).
+```
+
+Open `api.drawio` in [diagrams.net](https://app.diagrams.net/) and you
+get a two-page (or three-page in diff mode) view of your API.
+
+---
+
+## Why this exists
+
+API specs are easy to write and impossible to keep in your head once
+they grow past a handful of endpoints. swagger2drawio gives you a
+visual map you can annotate, share, and diff — without leaving the
+spec as the source of truth.
+
+## Features
+
+- **Two-page output**: an endpoints tree (root → tag → path → method)
+  and an ER-style schema map with `$ref` relationships.
+- **OpenAPI 3.x and Swagger 2.0** — auto-detected.
+- **Rich method labels**: parameters, request/response refs,
+  deprecated badge, summary.
+- **Schema composition**: `allOf` / `oneOf` / `anyOf` /
+  `discriminator` get distinct edge styles; enums render as their own
+  `«enum»` nodes.
+- **Spec validation** powered by `openapi-spec-validator` (skippable
+  with `--no-validate`).
+- **External `$ref` resolution**: relative-file and remote-URL
+  pointers are fetched and inlined; circular refs terminate cleanly.
+- **`diff` subcommand** — compare two spec versions and get a
+  green/red/yellow side-by-side change report. The headline feature.
+- **Bundled themes**: `light`, `dark`, `pastel`, `high-contrast`.
+- **Pluggable layouts** via the `swagger2drawio.layouts` entry point.
+
+## Install
+
+```bash
+# With uv (recommended)
+uvx swagger2drawio --version
+
+# With pip
+pip install swagger2drawio
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```bash
+# Generate a diagram from a local spec
+swagger2drawio generate -i openapi.yaml -o api.drawio
+
+# Generate from a live URL
+swagger2drawio generate \
+  -i https://petstore3.swagger.io/api/v3/openapi.json \
+  -o petstore.drawio
+
+# Use a built-in theme
+swagger2drawio generate -i openapi.yaml -o api.drawio --theme dark
+
+# Validate without rendering
+swagger2drawio validate openapi.yaml
+
+# Diff two versions of a spec
+swagger2drawio diff v1.yaml v2.yaml -o changes.drawio
+```
+
+## Commands
+
+| Command            | What it does                                              |
+| ------------------ | --------------------------------------------------------- |
+| `generate`         | Parse a spec and emit a `.drawio` file.                   |
+| `validate`         | Validate a spec against the OpenAPI / Swagger schema.     |
+| `diff`             | Compare two specs; render added/removed/changed overlay.  |
+| `init`             | Scaffold a `.swagger2drawio.yaml` in the current folder.  |
+| `themes list`      | List the bundled themes.                                  |
+| `themes show NAME` | Print one theme's YAML.                                   |
+
+Run `swagger2drawio <cmd> --help` for the full flag set on any command.
+
+## Key flags on `generate`
+
+| Flag                          | Purpose                                                                 |
+| ----------------------------- | ----------------------------------------------------------------------- |
+| `--input / -i`                | Path or HTTP(S) URL to the spec.                                        |
+| `--output / -o`               | Destination `.drawio` file (default: `output.drawio`).                  |
+| `--config / -c`               | Explicit YAML config file (highest precedence).                         |
+| `--theme NAME`                | One of the bundled themes (`light`, `dark`, `pastel`, `high-contrast`). |
+| `--group-by tag\|path\|auto`  | How to group operations on the endpoints page.                          |
+| `--layout hierarchical\|grid` | Layout strategy. Extensible via entry points.                           |
+| `--no-validate`               | Skip schema validation.                                                 |
+| `--timeout`                   | HTTP timeout in seconds (URL input).                                    |
+| `--header / -H "Name: v"`     | Extra HTTP header for URL input (repeatable).                           |
+| `--insecure`                  | Skip TLS verification (self-signed certs).                              |
+
+Global flags (any subcommand):
+
+| Flag             | Purpose                                          |
+| ---------------- | ------------------------------------------------ |
+| `--verbose / -v` | Increase log verbosity (`-v` INFO, `-vv` DEBUG). |
+| `--quiet / -q`   | Suppress INFO output.                            |
+| `--log-file`     | Append a DEBUG log to this file.                 |
+| `--version`      | Print the version and exit.                      |
+
+## Configuration
+
+The active config is resolved in this order (each layer deep-merged
+onto the previous):
+
+1. `--config` flag
+2. `--theme` (bundled YAML)
+3. `./.swagger2drawio.yaml`
+4. `$XDG_CONFIG_HOME/swagger2drawio/config.yaml` (defaults to
+   `~/.config/swagger2drawio/config.yaml`)
+5. Built-in defaults
+
+Run `swagger2drawio init` to drop a starter config in the current
+folder. `swagger2drawio themes show light` prints any bundled theme
+verbatim so you can copy the bits you want to tweak.
+
+## Shell completion
+
+```bash
+swagger2drawio --install-completion       # auto-detect shell
+swagger2drawio --show-completion          # print the script
+```
+
+Works with bash, zsh, fish, and PowerShell.
+
+## Use as a library
+
+```python
+from swagger2drawio.parser.openapi_parser import OpenAPIParser
+from swagger2drawio.layout.graph_engine import (
+    build_endpoint_graph,
+    build_schema_graph,
+)
+from swagger2drawio.renderer.drawio_builder import render
+from swagger2drawio.config_loader import load_config
+
+spec = OpenAPIParser(source="petstore.yaml").parse()
+cfg = load_config(None, theme="dark")
+ep = build_endpoint_graph(spec, group_by="tag", layout="hierarchical")
+sc = build_schema_graph(spec)
+render(ep, sc, "out.drawio", cfg)
+```
+
+For diffs:
+
+```python
+from swagger2drawio.diff import compute_diff
+from swagger2drawio.renderer.diff_renderer import render_diff
+
+old = OpenAPIParser(source="v1.yaml").parse(validate=False)
+new = OpenAPIParser(source="v2.yaml").parse(validate=False)
+diff = compute_diff(old, new)
+render_diff(old, new, diff, "changes.drawio")
+```
+
+## Exit codes
+
+Typed exceptions map to stable per-category exit codes so CI scripts
+can branch on the failure mode:
+
+| Code | Class                  | Meaning                            |
+| ---- | ---------------------- | ---------------------------------- |
+| 0    | —                      | Success                            |
+| 1    | `Swagger2DrawioError`  | Generic / unknown internal error   |
+| 2    | `SpecLoadError`        | File missing or URL fetch failed   |
+| 3    | `SpecParseError`       | Malformed JSON / YAML              |
+| 4    | `SpecValidationError`  | Fails OpenAPI / Swagger schema     |
+| 5    | `LayoutError`          | Graph construction / layout issue  |
+| 6    | `RenderError`          | drawpyo / XML emission failure     |
+| 7    | `ConfigError`          | Bad theme or config YAML           |
+
+## Development
+
+```bash
+git clone https://github.com/Abhishek-k03/swagger2drawio
+cd swagger2drawio
+uv sync --all-extras
+uv run pre-commit install
+uv run pytest                # full suite + coverage
+uv run ruff check .          # lint
+uv run mypy --strict swagger2drawio
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the longer setup and the
+custom-layout / custom-theme extension guide.
+
+## Project status
+
+Beta. Public API surface (Typer commands, exit codes, the dataclasses
+in `swagger2drawio.parser.openapi_parser`) is considered stable.
+Internal modules may change without notice.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Acknowledgements
+
+- [drawpyo](https://github.com/MerrimanInd/drawpyo) for the `.drawio`
+  XML writer.
+- [openapi-spec-validator](https://github.com/python-openapi/openapi-spec-validator)
+  for the schema validation pass.
+- [Typer](https://typer.tiangolo.com/) and
+  [Rich](https://rich.readthedocs.io/) for the CLI plumbing.

swagger2drawio-1.0.0/README.md

@@ -0,0 +1,221 @@
+# swagger2drawio
+
+[![CI](https://github.com/Abhishek-k03/swagger2drawio/actions/workflows/ci.yml/badge.svg)](https://github.com/Abhishek-k03/swagger2drawio/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/swagger2drawio.svg)](https://pypi.org/project/swagger2drawio/)
+[![Python versions](https://img.shields.io/pypi/pyversions/swagger2drawio.svg)](https://pypi.org/project/swagger2drawio/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> Turn an OpenAPI 3.x / Swagger 2.0 spec into a clean, structured
+> [draw.io](https://app.diagrams.net/) diagram. Local files, remote
+> URLs, multi-file `$ref`s — all in one command.
+
+```text
+$ swagger2drawio generate -i petstore.yaml -o api.drawio
+✔  api.drawio written (12.4 KB) — 8 path(s), 14 method(s), 6 schema(s).
+```
+
+Open `api.drawio` in [diagrams.net](https://app.diagrams.net/) and you
+get a two-page (or three-page in diff mode) view of your API.
+
+---
+
+## Why this exists
+
+API specs are easy to write and impossible to keep in your head once
+they grow past a handful of endpoints. swagger2drawio gives you a
+visual map you can annotate, share, and diff — without leaving the
+spec as the source of truth.
+
+## Features
+
+- **Two-page output**: an endpoints tree (root → tag → path → method)
+  and an ER-style schema map with `$ref` relationships.
+- **OpenAPI 3.x and Swagger 2.0** — auto-detected.
+- **Rich method labels**: parameters, request/response refs,
+  deprecated badge, summary.
+- **Schema composition**: `allOf` / `oneOf` / `anyOf` /
+  `discriminator` get distinct edge styles; enums render as their own
+  `«enum»` nodes.
+- **Spec validation** powered by `openapi-spec-validator` (skippable
+  with `--no-validate`).
+- **External `$ref` resolution**: relative-file and remote-URL
+  pointers are fetched and inlined; circular refs terminate cleanly.
+- **`diff` subcommand** — compare two spec versions and get a
+  green/red/yellow side-by-side change report. The headline feature.
+- **Bundled themes**: `light`, `dark`, `pastel`, `high-contrast`.
+- **Pluggable layouts** via the `swagger2drawio.layouts` entry point.
+
+## Install
+
+```bash
+# With uv (recommended)
+uvx swagger2drawio --version
+
+# With pip
+pip install swagger2drawio
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```bash
+# Generate a diagram from a local spec
+swagger2drawio generate -i openapi.yaml -o api.drawio
+
+# Generate from a live URL
+swagger2drawio generate \
+  -i https://petstore3.swagger.io/api/v3/openapi.json \
+  -o petstore.drawio
+
+# Use a built-in theme
+swagger2drawio generate -i openapi.yaml -o api.drawio --theme dark
+
+# Validate without rendering
+swagger2drawio validate openapi.yaml
+
+# Diff two versions of a spec
+swagger2drawio diff v1.yaml v2.yaml -o changes.drawio
+```
+
+## Commands
+
+| Command            | What it does                                              |
+| ------------------ | --------------------------------------------------------- |
+| `generate`         | Parse a spec and emit a `.drawio` file.                   |
+| `validate`         | Validate a spec against the OpenAPI / Swagger schema.     |
+| `diff`             | Compare two specs; render added/removed/changed overlay.  |
+| `init`             | Scaffold a `.swagger2drawio.yaml` in the current folder.  |
+| `themes list`      | List the bundled themes.                                  |
+| `themes show NAME` | Print one theme's YAML.                                   |
+
+Run `swagger2drawio <cmd> --help` for the full flag set on any command.
+
+## Key flags on `generate`
+
+| Flag                          | Purpose                                                                 |
+| ----------------------------- | ----------------------------------------------------------------------- |
+| `--input / -i`                | Path or HTTP(S) URL to the spec.                                        |
+| `--output / -o`               | Destination `.drawio` file (default: `output.drawio`).                  |
+| `--config / -c`               | Explicit YAML config file (highest precedence).                         |
+| `--theme NAME`                | One of the bundled themes (`light`, `dark`, `pastel`, `high-contrast`). |
+| `--group-by tag\|path\|auto`  | How to group operations on the endpoints page.                          |
+| `--layout hierarchical\|grid` | Layout strategy. Extensible via entry points.                           |
+| `--no-validate`               | Skip schema validation.                                                 |
+| `--timeout`                   | HTTP timeout in seconds (URL input).                                    |
+| `--header / -H "Name: v"`     | Extra HTTP header for URL input (repeatable).                           |
+| `--insecure`                  | Skip TLS verification (self-signed certs).                              |
+
+Global flags (any subcommand):
+
+| Flag             | Purpose                                          |
+| ---------------- | ------------------------------------------------ |
+| `--verbose / -v` | Increase log verbosity (`-v` INFO, `-vv` DEBUG). |
+| `--quiet / -q`   | Suppress INFO output.                            |
+| `--log-file`     | Append a DEBUG log to this file.                 |
+| `--version`      | Print the version and exit.                      |
+
+## Configuration
+
+The active config is resolved in this order (each layer deep-merged
+onto the previous):
+
+1. `--config` flag
+2. `--theme` (bundled YAML)
+3. `./.swagger2drawio.yaml`
+4. `$XDG_CONFIG_HOME/swagger2drawio/config.yaml` (defaults to
+   `~/.config/swagger2drawio/config.yaml`)
+5. Built-in defaults
+
+Run `swagger2drawio init` to drop a starter config in the current
+folder. `swagger2drawio themes show light` prints any bundled theme
+verbatim so you can copy the bits you want to tweak.
+
+## Shell completion
+
+```bash
+swagger2drawio --install-completion       # auto-detect shell
+swagger2drawio --show-completion          # print the script
+```
+
+Works with bash, zsh, fish, and PowerShell.
+
+## Use as a library
+
+```python
+from swagger2drawio.parser.openapi_parser import OpenAPIParser
+from swagger2drawio.layout.graph_engine import (
+    build_endpoint_graph,
+    build_schema_graph,
+)
+from swagger2drawio.renderer.drawio_builder import render
+from swagger2drawio.config_loader import load_config
+
+spec = OpenAPIParser(source="petstore.yaml").parse()
+cfg = load_config(None, theme="dark")
+ep = build_endpoint_graph(spec, group_by="tag", layout="hierarchical")
+sc = build_schema_graph(spec)
+render(ep, sc, "out.drawio", cfg)
+```
+
+For diffs:
+
+```python
+from swagger2drawio.diff import compute_diff
+from swagger2drawio.renderer.diff_renderer import render_diff
+
+old = OpenAPIParser(source="v1.yaml").parse(validate=False)
+new = OpenAPIParser(source="v2.yaml").parse(validate=False)
+diff = compute_diff(old, new)
+render_diff(old, new, diff, "changes.drawio")
+```
+
+## Exit codes
+
+Typed exceptions map to stable per-category exit codes so CI scripts
+can branch on the failure mode:
+
+| Code | Class                  | Meaning                            |
+| ---- | ---------------------- | ---------------------------------- |
+| 0    | —                      | Success                            |
+| 1    | `Swagger2DrawioError`  | Generic / unknown internal error   |
+| 2    | `SpecLoadError`        | File missing or URL fetch failed   |
+| 3    | `SpecParseError`       | Malformed JSON / YAML              |
+| 4    | `SpecValidationError`  | Fails OpenAPI / Swagger schema     |
+| 5    | `LayoutError`          | Graph construction / layout issue  |
+| 6    | `RenderError`          | drawpyo / XML emission failure     |
+| 7    | `ConfigError`          | Bad theme or config YAML           |
+
+## Development
+
+```bash
+git clone https://github.com/Abhishek-k03/swagger2drawio
+cd swagger2drawio
+uv sync --all-extras
+uv run pre-commit install
+uv run pytest                # full suite + coverage
+uv run ruff check .          # lint
+uv run mypy --strict swagger2drawio
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the longer setup and the
+custom-layout / custom-theme extension guide.
+
+## Project status
+
+Beta. Public API surface (Typer commands, exit codes, the dataclasses
+in `swagger2drawio.parser.openapi_parser`) is considered stable.
+Internal modules may change without notice.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Acknowledgements
+
+- [drawpyo](https://github.com/MerrimanInd/drawpyo) for the `.drawio`
+  XML writer.
+- [openapi-spec-validator](https://github.com/python-openapi/openapi-spec-validator)
+  for the schema validation pass.
+- [Typer](https://typer.tiangolo.com/) and
+  [Rich](https://rich.readthedocs.io/) for the CLI plumbing.