Markdown report command

Generate a markdown report of OpenAPI changes.

Use markdown-report when you want a shareable file instead of a terminal session. It renders the semantic change report as markdown, which makes it useful for pull requests, release notes, and internal docs.

Examples:

openapi-changes markdown-report ./ sample-specs/petstorev3.json

openapi-changes markdown-report HEAD~1:openapi.yaml ./openapi.yaml

Useful flags

Write to a specific file

Use --report-file to choose the output filename.

openapi-changes markdown-report --report-file changes.md ./ sample-specs/petstorev3.json

Include the raw unified diff

Use --include-diff to append a collapsible unified diff of the raw spec for each commit.

openapi-changes markdown-report --include-diff ./ sample-specs/petstorev3.json

Theme flags

The command also exposes the shared terminal theme flags:

openapi-changes markdown-report --tektronix ./ sample-specs/petstorev3.json

See Command Arguments for the shared flags.

Compact reports

Install with Go:

go install github.com/pb33f/openapi-changes@v0.3.0

Use --compact for counts and up to eight breaking-change highlights:

openapi-changes markdown-report --compact --report-file summary.md --result-file result.json HEAD~1:openapi.yaml HEAD:openapi.yaml

This mode accepts two files, URLs, or git revision paths. It does not accept repository history or --include-diff. Counts follow the same JSONPath + property deduplication as summary. The full Markdown report remains the default.

A completed comparison writes the compact report even when no changes exist. The optional --result-file writes semantic counts after the comparison and Markdown write succeed:

{"total":42,"breaking":18}

Valid breaking changes still exit successfully. This command writes a report; it does not apply a failure policy. Use summary to fail on breaking changes, or the GitHub Action to select a CI policy.

When reading result.json in automation, use a fresh output path and require command success first. A failed run does not delete an existing result file. The result file is not a replacement for the full JSON report.