swagger2drawio

Turn an OpenAPI 3.x / Swagger 2.0 spec into a clean, structured draw.io diagram. Local files, remote URLs, multi-file $refs — all in one command.

$ 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 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

# With uv (recommended)
uvx swagger2drawio --version

# With pip
pip install swagger2drawio

Requires Python 3.10+.

Quick start

# 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

Run swagger2drawio <cmd> --help for the full flag set on any command.

Key flags on generate

Global flags (any subcommand):

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

swagger2drawio --install-completion       # auto-detect shell
swagger2drawio --show-completion          # print the script

Works with bash, zsh, fish, and PowerShell.

Use as a library

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:

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:

Development

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 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.

Acknowledgements

• drawpyo for the .drawio XML writer.
• openapi-spec-validator for the schema validation pass.
• Typer and Rich for the CLI plumbing.