swagger2drawio 1.0.0__py3-none-any.whl

swagger2drawio/__init__.py

@@ -0,0 +1,3 @@
+"""swagger2drawio — Generate Draw.io diagrams from OpenAPI/Swagger specifications."""
+
+__version__ = "1.0.0"

swagger2drawio/_logging.py

@@ -0,0 +1,73 @@
+"""Logging configuration for the CLI.
+
+A single :func:`configure` entrypoint sets up the root ``swagger2drawio``
+logger so that all module-level loggers obtained via
+``logging.getLogger(__name__)`` honour the user's ``-v / -vv / -q /
+--log-file`` choices.
+
+Console output goes through Rich's :class:`~rich.logging.RichHandler`
+(colourised, with the module path). File output (when ``--log-file`` is
+set) uses a plain text formatter so the log is grep-friendly.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from rich.logging import RichHandler
+
+_ROOT_LOGGER = "swagger2drawio"
+
+
+def configure(verbosity: int = 0, quiet: bool = False, log_file: Path | None = None) -> None:
+    """Configure the package's root logger.
+
+    Args:
+        verbosity: ``0`` for default (WARNING+ on stderr), ``1`` for
+            INFO, ``2+`` for DEBUG.
+        quiet: When ``True``, force the console level to WARNING+ even
+            if *verbosity* is non-zero.
+        log_file: Optional path. When supplied, DEBUG-and-up messages
+            are appended to this file regardless of console verbosity.
+    """
+    root = logging.getLogger(_ROOT_LOGGER)
+    # Reset on every call so repeated CLI invocations in the same
+    # process (e.g. inside tests) don't stack handlers.
+    for handler in list(root.handlers):
+        root.removeHandler(handler)
+
+    # ── Console handler ──────────────────────────────────────
+    if quiet:
+        console_level = logging.WARNING
+    elif verbosity >= 2:
+        console_level = logging.DEBUG
+    elif verbosity == 1:
+        console_level = logging.INFO
+    else:
+        console_level = logging.WARNING
+
+    console = RichHandler(
+        rich_tracebacks=True,
+        show_path=False,
+        markup=False,
+        show_time=False,
+        show_level=True,
+    )
+    console.setLevel(console_level)
+    console.setFormatter(logging.Formatter("%(message)s"))
+    root.addHandler(console)
+
+    # ── File handler (always DEBUG) ──────────────────────────
+    if log_file is not None:
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        file_handler = logging.FileHandler(log_file, encoding="utf-8")
+        file_handler.setLevel(logging.DEBUG)
+        file_handler.setFormatter(
+            logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s")
+        )
+        root.addHandler(file_handler)
+
+    # Root level is the minimum so handlers can filter upward.
+    root.setLevel(min(console_level, logging.DEBUG if log_file else console_level))
+    root.propagate = False

swagger2drawio/cli.py

@@ -0,0 +1,464 @@
+"""Command-line interface for swagger2drawio.
+
+This module defines the Typer application and exposes the ``generate``
+command that drives the full pipeline:
+
+    1. Load theme / layout configuration (YAML).
+    2. Parse an OpenAPI specification (file or URL).
+    3. Build NetworkX graphs & compute layout coordinates.
+    4. Render the final ``.drawio`` file via *drawpyo*.
+
+Usage examples::
+
+    swagger2drawio generate --input openapi.yaml --output api.drawio
+    swagger2drawio generate --input https://petstore3.swagger.io/api/v3/openapi.json
+    swagger2drawio generate --input spec.yaml --config my_theme.yaml
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import typer
+
+from swagger2drawio import __version__
+from swagger2drawio._logging import configure as configure_logging
+from swagger2drawio.config_loader import (
+    list_builtin_themes,
+    load_config,
+    read_theme,
+)
+from swagger2drawio.exceptions import EXIT_CODE, Swagger2DrawioError
+from swagger2drawio.layout.graph_engine import build_endpoint_graph, build_schema_graph
+from swagger2drawio.parser.openapi_parser import OpenAPIParser
+from swagger2drawio.renderer.drawio_builder import render
+
+logger = logging.getLogger("swagger2drawio.cli")
+
+# ── Typer app ────────────────────────────────────────────────
+app = typer.Typer(
+    name="swagger2drawio",
+    help="Generate structured Draw.io diagrams from OpenAPI / Swagger specs.",
+    add_completion=True,
+)
+
+
+def _version_callback(value: bool) -> None:
+    """Print version and exit when ``--version`` is passed.
+
+    Args:
+        value: ``True`` when the flag is supplied.
+
+    Raises:
+        typer.Exit: Always exits after printing.
+    """
+    if value:
+        typer.echo(f"swagger2drawio {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool | None = typer.Option(
+        None,
+        "--version",
+        help="Show the application version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+    verbose: int = typer.Option(
+        0,
+        "--verbose",
+        "-v",
+        count=True,
+        help="Increase log verbosity (-v INFO, -vv DEBUG).",
+    ),
+    quiet: bool = typer.Option(
+        False,
+        "--quiet",
+        "-q",
+        help="Quiet mode: only WARNING and above.",
+    ),
+    log_file: Path | None = typer.Option(
+        None,
+        "--log-file",
+        help="Append a DEBUG-level log to this file (in addition to console output).",
+    ),
+) -> None:
+    """swagger2drawio — OpenAPI → Draw.io diagram generator."""
+    configure_logging(verbosity=verbose, quiet=quiet, log_file=log_file)
+
+
+@app.command()
+def generate(
+    input_source: str = typer.Option(
+        ...,
+        "--input",
+        "-i",
+        help="Path or URL to the OpenAPI/Swagger spec (JSON or YAML).",
+    ),
+    output: Path = typer.Option(
+        Path("output.drawio"),
+        "--output",
+        "-o",
+        help="Destination path for the generated .drawio file.",
+    ),
+    config: Path | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to an optional YAML theme/config file.",
+    ),
+    theme: str | None = typer.Option(
+        None,
+        "--theme",
+        help="Name of a bundled theme (see `swagger2drawio themes list`).",
+    ),
+    no_validate: bool = typer.Option(
+        False,
+        "--no-validate",
+        help="Skip OpenAPI / Swagger schema validation before rendering.",
+    ),
+    timeout: float = typer.Option(
+        10.0,
+        "--timeout",
+        help="HTTP timeout in seconds when --input is a URL.",
+    ),
+    header: list[str] = typer.Option(
+        None,
+        "--header",
+        "-H",
+        help="Extra HTTP header for URL input (repeatable, format: 'Name: value').",
+    ),
+    insecure: bool = typer.Option(
+        False,
+        "--insecure",
+        help="Skip TLS verification (self-signed certs). Use with care.",
+    ),
+    group_by: str = typer.Option(
+        "auto",
+        "--group-by",
+        help="Endpoint grouping: 'tag', 'path', or 'auto' (tag if any tags exist).",
+    ),
+    layout: str = typer.Option(
+        "hierarchical",
+        "--layout",
+        help="Layout strategy for the endpoint graph (e.g. 'hierarchical', 'grid').",
+    ),
+) -> None:
+    """Parse an OpenAPI spec and generate a Draw.io diagram.
+
+    The command performs the following pipeline:
+
+    1. **Config** — Loads the theme/layout YAML (falls back to built-in
+       defaults when *--config* is not supplied).
+    2. **Parse** — Reads the OpenAPI spec from a local file **or** a
+       remote URL, extracting paths/methods and component schemas.
+    3. **Layout** — Builds in-memory NetworkX graphs and computes (x, y)
+       coordinates using the *dot* algorithm.
+    4. **Render** — Writes a ``.drawio`` XML file with two pages:
+       *Endpoints Map* and *Schema (ER) Map*.
+
+    Args:
+        input_source: A local file path **or** an HTTP(S) URL pointing
+            to a valid OpenAPI 3.x / Swagger 2.x specification.
+        output: The filesystem path where the ``.drawio`` file will be
+            written.  Defaults to ``output.drawio`` in the current
+            working directory.
+        config: Optional path to a YAML file that overrides the default
+            visual theme (colours, node sizes, spacing, etc.).
+        theme: Optional name of a bundled theme (see
+            ``swagger2drawio themes list``). Stacked under ``config`` so
+            an explicit ``--config`` file can override individual theme
+            keys.
+        no_validate: When ``True``, skip the OpenAPI / Swagger schema
+            validation step. Useful when the spec is known-noncompliant
+            but you still want a diagram.
+        timeout: HTTP request timeout in seconds when ``input_source``
+            is a URL.
+        header: Repeatable list of ``"Name: value"`` HTTP headers for
+            URL input (e.g. ``--header "Authorization: Bearer ..."``).
+        insecure: When ``True``, skip TLS certificate verification.
+        group_by: How to group operations on the endpoints page.
+            ``"tag"`` roots the tree at API tags; ``"path"`` keeps the
+            flat structure; ``"auto"`` picks tag when any operation has
+            a tag, falling back to path.
+        layout: Name of the layout strategy. Built-ins are
+            ``"hierarchical"`` (the default BFS tree placement) and
+            ``"grid"`` (one row per weakly-connected component).
+            Third-party strategies registered via the entry-point
+            group ``swagger2drawio.layouts`` are also discoverable.
+    """
+    try:
+        if insecure:
+            typer.secho(
+                "⚠  TLS verification disabled (--insecure). Don't use against untrusted hosts.",
+                fg=typer.colors.YELLOW,
+                err=True,
+            )
+
+        parsed_headers = _parse_headers(header)
+
+        from rich.progress import (
+            BarColumn,
+            Progress,
+            SpinnerColumn,
+            TextColumn,
+            TimeElapsedColumn,
+        )
+
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[bold]{task.description}"),
+            BarColumn(bar_width=20),
+            TimeElapsedColumn(),
+            transient=False,
+        ) as progress:
+            task = progress.add_task("Loading configuration", total=4)
+            cfg = load_config(config, theme=theme)
+
+            progress.update(
+                task,
+                advance=1,
+                description="Parsing & validating spec" if not no_validate else "Parsing spec",
+            )
+            spec_data = OpenAPIParser(
+                source=input_source,
+                timeout=timeout,
+                headers=parsed_headers,
+                verify_ssl=not insecure,
+            ).parse(validate=not no_validate)
+
+            progress.update(task, advance=1, description="Computing layout")
+            layout_cfg = cfg.get("layout", {})
+            nw = layout_cfg.get("node_width", 200)
+            nh = layout_cfg.get("node_height", 60)
+            hs = layout_cfg.get("horizontal_spacing", 80)
+            vs = layout_cfg.get("vertical_spacing", 120)
+            rd = layout_cfg.get("rankdir", "TB")
+
+            ep_layout = build_endpoint_graph(
+                spec_data,
+                node_width=nw,
+                node_height=nh,
+                h_spacing=hs,
+                v_spacing=vs,
+                rankdir=rd,
+                group_by=group_by,
+                layout=layout,
+            )
+            sc_layout = build_schema_graph(
+                spec_data,
+                node_width=nw,
+                node_height=nh,
+                h_spacing=hs * 1.5,
+                v_spacing=vs * 1.3,
+            )
+
+            progress.update(task, advance=1, description=f"Rendering → {output.name}")
+            render(ep_layout, sc_layout, output, cfg, node_width=nw, node_height=nh)
+            progress.update(task, advance=1, description="Done")
+
+        # ── Final summary (after the live progress bar has closed) ──
+        endpoint_count = sum(len(p.methods) for p in spec_data.paths)
+        schema_count = len(spec_data.schemas)
+        size_bytes = output.stat().st_size if output.exists() else 0
+        size_kb = size_bytes / 1024
+        typer.secho(
+            f"✔  {output} written ({size_kb:.1f} KB) — "
+            f"{len(spec_data.paths)} path(s), {endpoint_count} method(s), "
+            f"{schema_count} schema(s).",
+            fg=typer.colors.GREEN,
+        )
+    except Swagger2DrawioError as exc:
+        _abort(exc)
+
+
+@app.command()
+def diff(
+    old: str = typer.Argument(..., metavar="OLD", help="Path or URL to the old spec."),
+    new: str = typer.Argument(..., metavar="NEW", help="Path or URL to the new spec."),
+    output: Path = typer.Option(
+        Path("changes.drawio"),
+        "--output",
+        "-o",
+        help="Destination .drawio file for the rendered diff.",
+    ),
+) -> None:
+    """Compare two specs and emit a colour-coded ``.drawio`` change report.
+
+    Args:
+        old: Path or URL to the earlier spec.
+        new: Path or URL to the later spec.
+        output: Destination ``.drawio`` file.
+    """
+    from swagger2drawio.diff import compute_diff
+    from swagger2drawio.renderer.diff_renderer import render_diff
+
+    try:
+        typer.echo(f"⏳ Parsing OLD spec: {old}")
+        old_parsed = OpenAPIParser(source=old).parse(validate=False)
+        typer.echo(f"⏳ Parsing NEW spec: {new}")
+        new_parsed = OpenAPIParser(source=new).parse(validate=False)
+
+        typer.echo("⏳ Computing diff …")
+        result = compute_diff(old_parsed, new_parsed)
+
+        if result.is_empty:
+            typer.secho("✔  No structural changes detected.", fg=typer.colors.GREEN)
+        else:
+            typer.echo(f"  paths   +{len(result.paths_added)} -{len(result.paths_removed)}")
+            typer.echo(
+                f"  methods +{len(result.methods_added)} -{len(result.methods_removed)} "
+                f"~{len(result.methods_changed)}"
+            )
+            typer.echo(
+                f"  schemas +{len(result.schemas_added)} -{len(result.schemas_removed)} "
+                f"~{len(result.schemas_changed)}"
+            )
+
+        typer.echo(f"⏳ Rendering diff → {output}")
+        render_diff(old_parsed, new_parsed, result, output)
+        typer.secho(f"✔  Diff diagram saved to {output}", fg=typer.colors.GREEN)
+    except Swagger2DrawioError as exc:
+        _abort(exc)
+
+
+@app.command()
+def validate(
+    input_source: str = typer.Argument(
+        ...,
+        metavar="SPEC",
+        help="Path or URL to the OpenAPI/Swagger spec to validate.",
+    ),
+) -> None:
+    """Validate an OpenAPI / Swagger spec without rendering anything.
+
+    Exits 0 when valid; otherwise prints the validator's message and
+    exits with the SpecValidationError exit code so CI scripts can react.
+
+    Args:
+        input_source: Local file path or HTTP(S) URL to the spec.
+    """
+    from swagger2drawio.parser.openapi_parser import _load_raw_spec
+    from swagger2drawio.validator import validate_spec
+
+    try:
+        typer.echo(f"⏳ Validating: {input_source}")
+        raw = _load_raw_spec(input_source)
+        validate_spec(raw)
+    except Swagger2DrawioError as exc:
+        _abort(exc)
+    else:
+        typer.secho("✔  Spec is valid.", fg=typer.colors.GREEN)
+
+
+# ── themes sub-app ───────────────────────────────────────────
+
+
+themes_app = typer.Typer(name="themes", help="List or print bundled themes.", no_args_is_help=True)
+app.add_typer(themes_app, name="themes")
+
+
+@themes_app.command("list")
+def themes_list() -> None:
+    """Print every bundled theme name, one per line."""
+    for name in list_builtin_themes():
+        typer.echo(name)
+
+
+@themes_app.command("show")
+def themes_show(name: str = typer.Argument(..., help="Theme name (e.g. 'dark').")) -> None:
+    """Print the resolved YAML of one bundled theme.
+
+    Args:
+        name: Theme name (without ``.yaml``).
+    """
+    try:
+        data = read_theme(name)
+    except Swagger2DrawioError as exc:
+        _abort(exc)
+    import yaml as _yaml
+
+    typer.echo(_yaml.safe_dump(data, sort_keys=False))
+
+
+# ── init subcommand ──────────────────────────────────────────
+
+
+@app.command()
+def init(
+    theme: str = typer.Option(
+        "light",
+        "--theme",
+        help="Bundled theme to scaffold from (light / dark / pastel / high-contrast).",
+    ),
+    force: bool = typer.Option(False, "--force", help="Overwrite an existing config file."),
+) -> None:
+    """Scaffold a ``.swagger2drawio.yaml`` in the current directory.
+
+    Args:
+        theme: Name of the bundled theme to copy as the starter file.
+        force: Overwrite an existing file instead of refusing.
+    """
+    import yaml as _yaml
+
+    target = Path.cwd() / ".swagger2drawio.yaml"
+    if target.exists() and not force:
+        typer.secho(
+            f"✖  {target.name} already exists; pass --force to overwrite.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1)
+    try:
+        data = read_theme(theme)
+    except Swagger2DrawioError as exc:
+        _abort(exc)
+    target.write_text(_yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
+    typer.secho(f"✔  Wrote {target}", fg=typer.colors.GREEN)
+
+
+def _parse_headers(raw: list[str] | None) -> dict[str, str] | None:
+    """Convert a list of ``"Name: value"`` strings into a header dict.
+
+    Args:
+        raw: List of strings as collected from ``--header / -H`` (may be
+            ``None`` if the flag was not passed).
+
+    Returns:
+        ``None`` when no headers were supplied; otherwise a dict mapping
+        header name to value.
+
+    Raises:
+        typer.BadParameter: If any entry is missing the ``:`` separator.
+    """
+    if not raw:
+        return None
+    parsed: dict[str, str] = {}
+    for entry in raw:
+        if ":" not in entry:
+            raise typer.BadParameter(f"Invalid --header value: {entry!r}. Expected 'Name: value'.")
+        name, _, value = entry.partition(":")
+        parsed[name.strip()] = value.strip()
+    return parsed
+
+
+def _abort(exc: Swagger2DrawioError) -> None:
+    """Print a clean error and exit with the code mapped to *exc*'s class.
+
+    Args:
+        exc: The typed exception to report.
+
+    Raises:
+        typer.Exit: Always raised with the appropriate code.
+    """
+    code = EXIT_CODE.get(type(exc), EXIT_CODE[Swagger2DrawioError])
+    typer.secho(f"✖  {type(exc).__name__}: {exc}", fg=typer.colors.RED, err=True)
+    raise typer.Exit(code=code) from exc
+
+
+# Allow ``python -m swagger2drawio.cli`` execution.
+if __name__ == "__main__":
+    app()