swagger2drawio 1.0.0

Generate structured Draw.io diagrams from OpenAPI 3.x / Swagger 2.0 specs.

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

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

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:

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

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.