pb33f/openapi-changes

openapi-changes Docker image

https://hub.docker.com/r/pb33f/openapi-changes

openapi-changes detects and explores semantic changes between OpenAPI and Swagger specifications.

This image packages the openapi-changes CLI so you can generate terminal summaries, JSON reports, markdown reports, and self-contained offline HTML reports without installing Go, npm, Homebrew, or a local binary.

Images

Images are published to both Docker Hub and GitHub Container Registry:

pb33f/openapi-changes:latest
ghcr.io/pb33f/openapi-changes:latest

Release tags are also published alongside latest. Images are available for linux/amd64 and linux/arm64.

Quick check

docker run --rm pb33f/openapi-changes:latest version
docker run --rm ghcr.io/pb33f/openapi-changes:latest version

Compare two local specs

Mount your current directory into /work and run a summary against two local OpenAPI files:

docker run --rm \
  -v "$PWD:/work:rw" \
  pb33f/openapi-changes:latest \
  summary ./openapi-old.yaml ./openapi.yaml

Generate a JSON report

docker run --rm \
  -v "$PWD:/work:rw" \
  pb33f/openapi-changes:latest \
  report ./openapi-old.yaml ./openapi.yaml > openapi-changes-report.json

Generate a markdown report

docker run --rm \
  -v "$PWD:/work:rw" \
  pb33f/openapi-changes:latest \
  markdown-report ./openapi-old.yaml ./openapi.yaml > openapi-changes-report.md

Generate an offline HTML report

The HTML report is self-contained and works offline:

docker run --rm \
  -v "$PWD:/work:rw" \
  pb33f/openapi-changes:latest \
  html-report --report-file ./report.html ./openapi-old.yaml ./openapi.yaml

Compare git revisions

The image includes Git and trusts mounted repositories, so revision:path comparisons work inside the container:

docker run --rm \
  -v "$PWD:/work:rw" \
  pb33f/openapi-changes:latest \
  summary HEAD~1:openapi.yaml ./openapi.yaml

docker run --rm \
  -v "$PWD:/work:rw" \
  pb33f/openapi-changes:latest \
  html-report --report-file ./report.html main:api/openapi.yaml feature-branch:api/openapi.yaml

Interactive console

Allocate a TTY when using the interactive terminal UI:

docker run --rm -it \
  -v "$PWD:/work:rw" \
  pb33f/openapi-changes:latest \
  console HEAD~1:openapi.yaml ./openapi.yaml

Custom breaking-change rules

Mount your rules file with the specs and pass it with -c:

docker run --rm \
  -v "$PWD:/work:rw" \
  pb33f/openapi-changes:latest \
  summary -c ./changes-rules.yaml ./openapi-old.yaml ./openapi.yaml

Useful links

• Quick start guide
• Installing openapi-changes
• Command arguments
• Summary command
• HTML report command
• https://github.com/pb33f/openapi-changes
• ***

openapi-changes is a product of Princess Beef Heavy Industries, LLC.