---
name: "api-changelog-generator"
description: "Compare two OpenAPI documents and explain contract changes to API consumers. Use when the user needs: Get a changelog with path-level evidence and breaking-change candidates."
metadata: {"version": "2026-10-17.1", "category": "code-development", "publisher": "AIDiveForge"}
---

# API Changelog Generator

Get a changelog with path-level evidence and breaking-change candidates.

## Requirements

Provide both specifications and their OpenAPI version; a parser is needed for local schema validation.

## Workflow

1. Validate both documents and resolve local references before comparing operations.
2. Match operations by path and method, then compare parameters, request bodies, responses and security requirements.
3. Treat removal, new required inputs and narrower accepted values as possible breaking changes; distinguish response additions from request restrictions.
4. Keep implementation behavior separate from the documented contract and flag unresolved references.
5. Return consumer actions and exact before/after locations; do not label every textual edit as a breaking change.

## Worked example

Read `examples/input.txt` and `examples/expected.txt` before adapting the workflow.

## Acceptance checks

Identify the required-input change without automatically treating an additive response field as universally safe or breaking.

## Limits

A specification diff does not prove server behavior. Test representative clients before claiming compatibility.

Worked example included. Model-specific performance and vendor compatibility have not been benchmarked.