{"id":13455875,"url":"https://github.com/pb33f/openapi-changes","last_synced_at":"2026-04-14T03:02:00.162Z","repository":{"id":64617979,"uuid":"571681922","full_name":"pb33f/openapi-changes","owner":"pb33f","description":"The world's sexiest OpenAPI breaking changes detector. Discover what changed between two OpenAPI specs, or a single spec over time. Supports OpenAPI 3.1, 3.0 and Swagger","archived":false,"fork":false,"pushed_at":"2024-10-22T14:02:57.000Z","size":45890,"stargazers_count":184,"open_issues_count":42,"forks_count":16,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-29T17:29:11.757Z","etag":null,"topics":["diff","oas3","openapi","openapi-generator","openapi-repo","openapi-spec","openapi-specification","openapi3","swagger"],"latest_commit_sha":null,"homepage":"https://pb33f.io/openapi-changes/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pb33f.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-28T16:53:14.000Z","updated_at":"2024-10-28T10:17:56.000Z","dependencies_parsed_at":"2023-11-30T13:46:28.363Z","dependency_job_id":"fc94fe5e-2f54-4b0d-bab8-6fffe1b89e0d","html_url":"https://github.com/pb33f/openapi-changes","commit_stats":{"total_commits":196,"total_committers":7,"mean_commits":28.0,"dds":0.04591836734693877,"last_synced_commit":"4417e5a365d2cf9ba116aa978bde39976c174029"},"previous_names":[],"tags_count":75,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pb33f%2Fopenapi-changes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pb33f%2Fopenapi-changes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pb33f%2Fopenapi-changes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pb33f%2Fopenapi-changes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pb33f","download_url":"https://codeload.github.com/pb33f/openapi-changes/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247721898,"owners_count":20985084,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["diff","oas3","openapi","openapi-generator","openapi-repo","openapi-spec","openapi-specification","openapi3","swagger"],"created_at":"2024-07-31T08:01:12.691Z","updated_at":"2026-04-14T03:02:00.157Z","avatar_url":"https://github.com/pb33f.png","language":"Go","readme":"![logo](openapi-changes-logo.webp)\n\n[![discord](https://img.shields.io/discord/923258363540815912)](https://discord.gg/x7VACVuEGP)\n[![GitHub downloads](https://img.shields.io/github/downloads/pb33f/openapi-changes/total?label=github%20downloads\u0026style=flat-square)](https://github.com/pb33f/openapi-changes/releases)\n[![npm](https://img.shields.io/npm/dm/@pb33f/openapi-changes?style=flat-square\u0026label=npm%20downloads)](https://www.npmjs.com/package/@pb33f/openapi-changes)\n[![Docker Pulls](https://img.shields.io/docker/pulls/pb33f/openapi-changes?style=flat-square)](https://hub.docker.com/r/pb33f/openapi-changes)\n\n# OpenAPI Changes\n\n## The world's **_most powerful and complete_** OpenAPI diff tool.\n\n`openapi-changes` lets you inspect what changed in an OpenAPI specification between two files,\nbetween git revisions of the same file, across local git history, or directly from a GitHub-hosted file URL.\n\nIt can render the same semantic change model as:\n\n- an interactive terminal UI\n- a terminal summary\n- a machine-readable JSON report\n- a markdown report\n- a self-contained offline HTML report\n\nIt works well for local exploration, CI/CD checks, release notes, and API review workflows.\n\n## How is it the 'most powerful and complete?'?\n\nopenapi-changes gives you the power to view all changes between two OpenAPI contracts, and over time in every which\nway you can possibly think of. Graphs, trees, lists, diffs, JSON, mark down.\n\nHas no network dependencies at all. Runs 100% offline, including the HTML report.\n\n---\n\n## Install with Homebrew\n\n```bash\nbrew install pb33f/taps/openapi-changes\n```\n\n## Install with npm or yarn\n\n```bash\nnpm i -g @pb33f/openapi-changes\n```\n\nIf you prefer yarn:\n\n```bash\nyarn global add @pb33f/openapi-changes\n```\n\n## Install with cURL\n\n```bash\ncurl -fsSL https://pb33f.io/openapi-changes/install.sh | sh\n```\n\n## Install or run with Docker\n\n```bash\ndocker pull pb33f/openapi-changes\n```\n\nDocker images are available for both `linux/amd64` and `linux/arm64`.\n\nThe published image configures Git to trust mounted repositories, so local git-history commands work without requiring extra `safe.directory` setup inside the container.\n\nTo run a command, mount the current working directory into the container:\n\n```bash\ndocker run --rm -v $PWD:/work:rw pb33f/openapi-changes summary . sample-specs/petstorev3.json\n```\n\nTo run the interactive `console` through Docker, allocate a TTY with `-it`:\n\n```bash\ndocker run --rm -it -v $PWD:/work:rw pb33f/openapi-changes console . path/to/openapi.yaml\n```\n\n## Verify the install\n\nPrint the installed version:\n\n```bash\nopenapi-changes version\n```\n\n---\n\n### Summary view\n\n![](./.github/assets/summary.gif)\n\n\n### A full terminal UI\n\nComes in multiple themes! PB33F (Dark), Roger Mode (Light) and Tektronix (Retro Dark)\n\n![](./.github/assets/console.gif)\n\n\n### Powerful HTML report with no rival.\n\nA self-contained, offline HTML report with interactive timeline, change explorer graph, diff views, and more.\n\n#### Timeline overview with change history chart\n\n![](./.github/assets/timeline-overview.png)\n\n#### Interactive explorer graph\n\n![](./.github/assets/timline-explorer.png)\n\n![](./.github/assets/explorer-deletion.png)\n\n#### Change report breakdown\n\n![](./.github/assets/change-report.png)\n\n![](./.github/assets/change-list.png)\n\n#### Side by side, focused, unified or inline diffing\n\n![](./.github/assets/file-diff.png)\n\n![](./.github/assets/focus-diff.png)\n\n#### Roger mode (monochrome light theme)\n\n![](./.github/assets/roger-mode-explorer.png)\n\n![](./.github/assets/roger-mode-items.png)\n\n#### Tektronix mode (green monochrome)\n\n![](./.github/assets/tektronix.png)\n\n---\n\n## Comparing git revisions\n\nCompare a file at different git revisions without checking out branches:\n\n```bash\nopenapi-changes summary HEAD~1:openapi.yaml ./openapi.yaml\nopenapi-changes html-report main:api/openapi.yaml feature-branch:api/openapi.yaml\n```\n\nThe `revision:path` syntax works with any git ref -- branches, tags, `HEAD~N`, commit SHAs.\nThe path is relative to the repository root. This works with all commands and supports\nmulti-file specs with `$ref` references resolved from the same revision.\n\n---\n\n## Documentation\n\n### [Quick Start Guide 🚀](https://pb33f.io/openapi-changes/quickstart/)\n\nFull docs: https://pb33f.io/openapi-changes/\n\n- [Installing openapi-changes](https://pb33f.io/openapi-changes/installing/)\n- [Configuring breaking changes](https://pb33f.io/openapi-changes/configuring/)\n- [Command arguments](https://pb33f.io/openapi-changes/command-arguments/)\n- Commands:\n  - [`console`](https://pb33f.io/openapi-changes/console/)\n  - [`summary`](https://pb33f.io/openapi-changes/summary/)\n  - [`report`](https://pb33f.io/openapi-changes/report/)\n  - [`markdown-report`](https://pb33f.io/openapi-changes/markdown-report/)\n  - [`html-report`](https://pb33f.io/openapi-changes/html-report/)\n  - [`completion`](https://pb33f.io/openapi-changes/completion/)\n  - [`version`](https://pb33f.io/openapi-changes/version/)\n- [About openapi-changes](https://pb33f.io/openapi-changes/about/)\n\n---\n\n## Build from source\n\n`openapi-changes` currently requires Go `1.25.0`.\n\n```bash\ngit clone https://github.com/pb33f/openapi-changes.git\ncd openapi-changes\ngo build -o bin/openapi-changes .\n```\n\nOr use `make`:\n\n```bash\nmake\n```\n\n---\n\n## Command overview\n\nThe current command surface is:\n\n- `console` for the interactive terminal UI\n- `summary` for fast terminal and CI output\n- `report` for machine-readable JSON\n- `markdown-report` for shareable markdown output\n- `html-report` for the interactive offline browser report\n- `completion` for shell completion scripts\n- `version` for raw build version output\n\nRun `openapi-changes --help` or `openapi-changes \u003ccommand\u003e --help` for the live CLI surface.\n\n### Terminal themes\n\nThe terminal-facing commands support multiple presentation modes:\n\n- `--no-color` for the light Roger monochrome theme\n- `--roger-mode` as an alias for `--no-color`\n- `--tektronix` for the green monochrome terminal theme\n\nSee the [command arguments docs](https://pb33f.io/openapi-changes/command-arguments/) for the full shared flag set.\n\n---\n\n## Custom breaking rules configuration\n\n`openapi-changes` supports configurable breaking-change rules via `changes-rules.yaml`.\n\n### Use an explicit config file\n\n```bash\nopenapi-changes summary -c my-rules.yaml old.yaml new.yaml\n```\n\n### Or let it auto-discover the default config file\n\n```bash\nopenapi-changes summary old.yaml new.yaml\n```\n\nDefault lookup locations:\n\n1. `./changes-rules.yaml`\n2. `~/.config/changes-rules.yaml`\n\n### Example\n\n```yaml\npathItem:\n  get:\n    removed: false\n  post:\n    removed: false\n  put:\n    removed: false\n  delete:\n    removed: false\n\nschema:\n  enum:\n    removed: false\n\nparameter:\n  required:\n    modified: false\n```\n\nEach rule supports:\n\n- `added`\n- `modified`\n- `removed`\n\nFor the full rules reference and more examples, see the\n[configuration docs](https://pb33f.io/openapi-changes/configuring/).\n\n---\n\nSee the full docs at https://pb33f.io/openapi-changes/\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpb33f%2Fopenapi-changes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpb33f%2Fopenapi-changes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpb33f%2Fopenapi-changes/lists"}