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.
