Skip to content
Docs navigationBrowse tools →

Tool docs

Swagger Doc Tool

Validate, normalize, diff, preview, and export Swagger or OpenAPI specs locally. This guide explains where the tool helps most, what its MVP checks actually cover, and where you still need deeper contract review.

Tool

Overview

01

Swagger Doc Tool

The Swagger Doc Tool is aimed at quick spec inspection and review: load a document, surface obvious schema hygiene issues, produce deterministic output, and compare two versions for likely breaking changes without leaving the browser.

Guide

Common usage patterns

01

Validation, canonicalization, and diff review

  • Paste or upload a Swagger/OpenAPI spec in JSON or YAML.
  • Review validation messages before trusting a spec for downstream tooling.
  • Use canonical output to get a more stable diff when files contain noisy ordering changes.
  • Compare a base and target spec when you want a lightweight breaking-change review before merge.
  • Export a single-file static HTML page when you want something deployable without further tooling.

Guide

Edge cases & common pitfalls

01

What this tool can and cannot prove

  • Missing info fields, paths, duplicate operationIds, or absent 2xx responses are useful signals, but they are not the whole contract story.
  • Generated fields and unstable ordering can create noisy diffs if you do not normalize first.
  • Swagger/OpenAPI version differences can still require manual judgment.
  • The breaking-change rules are intentionally heuristic; use them as review input, not as a substitute for formal API governance.

Internals

How it works internally

01

Local parsing, normalization, and lightweight diffing

Birdor parses JSON or YAML locally, normalizes output into a deterministic shape, and computes a lightweight diff summary in the browser. The goal is fast reviewability, not a full schema theorem prover.