API-Changelog automatisch aus OpenAPI-Diffs generieren: Vom strukturellen Diff zum lesbaren Text

1. Warum handgepflegte Changelogs an der Realität scheitern

In der Theorie soll jeder Entwickler, der eine API-Änderung merged, gleichzeitig einen Eintrag im Changelog ergänzen. In der Praxis gerät dieser zweite Schritt regelmäßig unter die Räder, weil er außerhalb des eigentlichen Codes stattfindet, keine Tests dafür existieren und ein vergessener Eintrag beim Code-Review selten auffällt, solange die Funktionalität selbst korrekt ist. Nach einigen Monaten enthält der Changelog dann eine Mischung aus detaillierten Einträgen für unwichtige Änderungen und fehlenden Einträgen für echte Breaking Changes, was das Dokument für Consumer-Teams faktisch wertlos macht.

Das Problem verschärft sich, sobald mehrere Teams parallel an unterschiedlichen Teilen derselben API arbeiten, denn dann existiert oft nicht einmal ein einzelner verantwortlicher Redakteur, der alle Änderungen überblickt. Ein struktureller Diff zwischen zwei OpenAPI-Dokumenten kennt dieses Problem nicht: Er sieht jede Änderung, die tatsächlich in der Spezifikation gelandet ist, unabhängig davon, ob der ursprüngliche Entwickler daran gedacht hat, sie zu dokumentieren. Damit verschiebt sich die Aufgabe von 'daran denken, alles zu dokumentieren' zu 'die bereits vorhandenen strukturierten Daten in lesbaren Text übersetzen', was deutlich zuverlässiger automatisierbar ist.

2. Was ein struktureller OpenAPI-Diff tatsächlich liefert

Ein Diff-Tool wie oasdiff vergleicht zwei OpenAPI-Dokumente nicht zeilenweise wie ein klassisches Textdiff, sondern semantisch entlang der Struktur: neue Pfade, entfernte Pfade, neue oder entfernte HTTP-Methoden je Pfad, neue oder entfernte Parameter, geänderte Parametertypen, neue oder entfernte Felder in Request- und Response-Schemas, geänderte Pflichtfeld-Status, neue oder entfernte Enum-Werte, sowie Änderungen an Sicherheitsanforderungen wie einem neu verlangten Scope. Jede dieser Kategorien lässt sich eindeutig einer Änderungsart zuordnen, additiv, entfernend oder modifizierend, und genau diese Kategorisierung ist die Grundlage für einen automatisch generierten Changelog-Eintrag.

Der Output von oasdiff changelog liefert bereits eine strukturierte Liste von Einträgen im JSON- oder YAML-Format, jeder mit einem eindeutigen Änderungstyp wie endpoint-added, request-property-removed oder response-required-property-added, sowie dem betroffenen Pfad und der betroffenen HTTP-Methode. Diese maschinenlesbare Struktur ist der entscheidende Unterschied zu einem handgeschriebenen Changelog: Sie lässt sich in eine Vorlage einsetzen, nach Kategorie gruppieren und automatisch nach Breaking Changes sortiert an den Anfang des Dokuments stellen, ohne dass ein Mensch die Rohdaten je gesehen haben muss.

3. Vom strukturierten Diff zum lesbaren Changelog-Entwurf

Der Übergang vom rohen Diff zum lesbaren Text geschieht über eine Vorlagen-Engine, die jeden Änderungstyp auf einen vorformulierten Satzbaustein abbildet. Ein Eintrag vom Typ request-property-added mit dem Namen 'discountCode' wird so automatisch zu 'Der optionale Parameter discountCode wurde im Request des Endpoints POST /api/v2/orders ergänzt', während ein Eintrag vom Typ response-property-removed zu 'Das Feld legacyId wurde aus der Response von GET /api/v2/orders/{id} entfernt (Breaking Change)' wird. Diese Textbausteine müssen nicht perfekt formuliert sein, denn sie sind explizit als Entwurf gedacht, nicht als finaler, veröffentlichter Text.

In einem Symfony-Projekt lässt sich dieser Schritt gut als eigenes Console-Command umsetzen, das die JSON-Ausgabe von oasdiff changelog einliest, über Twig-Templates in Markdown rendert und das Ergebnis als Entwurfsdatei im Repository ablegt. Der folgende Ausschnitt zeigt ein solches Command, das die rohen Diff-Einträge in kategorisierte Markdown-Abschnitte übersetzt, wobei Breaking Changes bewusst zuerst aufgelistet werden, damit ein Redakteur sie beim Lesen nicht übersehen kann.

<?php

declare(strict_types=1);

namespace App\Command;

use App\Service\ChangelogEntryFormatter;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

/**
 * Liest die JSON-Ausgabe von "oasdiff changelog" ein und rendert daraus
 * einen kategorisierten Markdown-Entwurf für die redaktionelle
 * Nachbearbeitung.
 */
#[AsCommand(name: 'app:api:changelog-draft', description: 'Erzeugt einen Changelog-Entwurf aus einem OpenAPI-Diff')]
final class GenerateChangelogDraftCommand extends Command
{
    public function __construct(
        private readonly ChangelogEntryFormatter $formatter,
    ) {
        parent::__construct();
    }

    protected function configure(): void
    {
        $this->addArgument('diffJsonPath', InputArgument::REQUIRED, 'Pfad zur oasdiff-JSON-Datei');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        /** @var string $path */
        $path = $input->getArgument('diffJsonPath');

        $rawDiff = json_decode(
            file_get_contents($path) ?: '[]',
            true,
            512,
            JSON_THROW_ON_ERROR,
        );

        $breaking = [];
        $additions = [];
        $other = [];

        foreach ($rawDiff as $entry) {
            $line = $this->formatter->format($entry);

            match (true) {
                $entry['level'] === 'error' => $breaking[] = $line,
                str_ends_with((string) $entry['id'], '-added') => $additions[] = $line,
                default => $other[] = $line,
            };
        }

        $output->writeln('## Breaking Changes');
        $output->writeln($breaking ?: ['Keine Breaking Changes in dieser Version.']);
        $output->writeln('## Neue Funktionen');
        $output->writeln($additions ?: ['Keine additiven Änderungen in dieser Version.']);
        $output->writeln('## Weitere Änderungen');
        $output->writeln($other ?: ['Keine weiteren Änderungen.']);

        return Command::SUCCESS;
    }
}

4. Kategorisierung nach Schweregrad statt nach Reihenfolge

Ein automatisch generierter Changelog ist nur dann wirklich nützlich, wenn er nicht einfach chronologisch alle Änderungen auflistet, sondern nach Relevanz für den Leser sortiert. In der Praxis hat sich eine Dreiteilung bewährt: zuoberst Breaking Changes, die eine aktive Anpassung beim Consumer erfordern, danach neue Funktionen, die additiv und ungefährlich sind, aber für manche Teams relevant sein könnten, und zuletzt interne oder kosmetische Änderungen wie korrigierte Beschreibungstexte, die für die meisten Leser irrelevant sind, aber aus Vollständigkeitsgründen trotzdem dokumentiert werden sollten.

Diese Kategorisierung lässt sich direkt aus den von oasdiff gelieferten Severity-Leveln ableiten, die Änderungen bereits in error (breaking), warning (potenziell relevant) und info (rein informativ) einteilen. Ein gutes Changelog-Template nutzt diese Level, um automatisch Überschriften und eine sinnvolle Reihenfolge zu erzeugen, sodass ein Consumer-Team beim Lesen sofort erkennt, ob eine Reaktion nötig ist, ohne die komplette Liste durchgehen zu müssen. Diese Struktur allein macht bereits einen großen Teil des Werts eines guten Changelogs aus, noch bevor ein Mensch einen einzigen Satz umformuliert hat.

5. Wo die reine Automatisierung an ihre Grenzen stößt

Ein automatisch generierter Eintrag beschreibt zuverlässig, WAS sich strukturell geändert hat, aber selten WARUM. Ein Consumer-Entwickler möchte oft nicht nur wissen, dass ein Feld entfernt wurde, sondern auch, wodurch er es ersetzen soll und ob eine Migration nötig ist. Diese Kontextinformation steckt nicht in der OpenAPI-Spezifikation selbst, sondern nur im Kopf des Entwicklers, der die Änderung vorgenommen hat, und muss deshalb manuell ergänzt werden. Ebenso kann ein automatisiertes Tool nicht einschätzen, ob eine Änderung für die meisten Consumer irrelevant ist, weil sie ohnehin niemand nutzt, oder ob sie kritisch ist, weil ein großer interner Kunde genau dieses Feld auswertet.

Ein weiterer blinder Fleck betrifft semantische Änderungen, die sich strukturell nicht im Schema niederschlagen: Wenn sich lediglich die Bedeutung eines Feldes ändert, etwa weil ein Preisfeld plötzlich inklusive statt exklusive Mehrwertsteuer zurückgegeben wird, bleibt der Typ des Feldes identisch, und ein struktureller Diff erkennt hier gar keine Änderung, obwohl es sich um einen gravierenden Breaking Change handelt. Solche Fälle lassen sich nur durch eine bewusste, manuelle Ergänzung im Changelog abfangen, weshalb reine Automatisierung niemals als alleinige Quelle der Wahrheit taugt, sondern immer als Ausgangspunkt für eine redaktionelle Prüfung gedacht sein muss.

6. Changelog-Einträge für interne und externe Leser differenzieren

Nicht jeder Consumer eines Changelogs hat dieselben Informationsbedürfnisse. Ein internes Frontend-Team, das denselben Release-Zyklus wie das Backend-Team teilt, möchte möglichst jede Änderung sehen, auch kleinere interne Refactorings, weil es direkten Einfluss auf den nächsten eigenen Sprint hat. Ein externer Partner, der die API nur alle paar Monate an eine neue Version anpasst, will dagegen vor allem wissen, was sich seit seiner zuletzt integrierten Version tatsächlich für ihn geändert hat, und wird von einer langen Liste rein interner Refactorings eher abgeschreckt als informiert. Ein automatisch generierter Changelog sollte deshalb nicht als ein einziges, universelles Dokument gedacht werden, sondern als eine strukturierte Datenquelle, aus der sich unterschiedliche Sichten filtern lassen.

Technisch lässt sich das gut über ein zusätzliches Attribut je Changelog-Eintrag lösen, etwa eine Sichtbarkeits-Kennung wie audience: internal oder audience: public, die bereits während der Generierung aus dem OpenAPI-Diff gesetzt wird, zum Beispiel indem alle Änderungen an intern markierten Endpunkten automatisch als intern klassifiziert werden. Der öffentliche Changelog-Endpoint filtert dann konsequent auf audience: public, während die interne CHANGELOG.md im Repository weiterhin die vollständige, ungefilterte Liste enthält. Dieser kleine Zusatzaufwand bei der Generierung erspart es dem Redakteur, bei jedem Release von Hand zu entscheiden, welche Einträge für welches Publikum relevant sind.

7. Der Weg von der Automatisierung zur redaktionellen Nachbearbeitung

In einem funktionierenden Workflow entsteht der Changelog-Entwurf automatisch bei jedem Release-Kandidaten und landet als Pull Request oder als Kommentar im bestehenden Release-Pull-Request, statt direkt veröffentlicht zu werden. Ein technischer Redakteur, oder in kleineren Teams der verantwortliche Entwickler selbst, geht diesen Entwurf durch, ergänzt Migrationsempfehlungen bei Breaking Changes, entfernt irrelevante interne Änderungen und formuliert die automatisch generierten Sätze in einen konsistenten, kundenfreundlichen Ton um. Dieser Schritt dauert bei einem gut vorbereiteten Entwurf deutlich weniger als eine Stunde, während das komplett manuelle Verfassen eines Changelogs bei einer größeren API leicht einen halben Tag beanspruchen kann.

Wichtig ist, diesen redaktionellen Schritt nicht als optional zu behandeln, auch wenn der automatische Entwurf bereits gut lesbar ist. Ein rein maschinell erzeugter Changelog fühlt sich für Leser oft technisch und unpersönlich an, während eine kurze redaktionelle Überarbeitung, etwa das Ergänzen eines einleitenden Satzes zur wichtigsten Änderung des Releases, den gesamten Text deutlich zugänglicher macht. Die Kombination aus zuverlässiger struktureller Vollständigkeit und gezielter menschlicher Nacharbeit liefert am Ende ein Ergebnis, das weder eine rein automatisierte noch eine rein manuelle Lösung allein erreichen würde.

8. Integration in den bestehenden Release-Prozess

Damit die Changelog-Generierung nicht zu einem weiteren manuellen Schritt wird, den jemand vergessen kann, sollte sie fest in die CI-Pipeline integriert werden. Ein sinnvoller Ablauf sieht so aus: Bei jedem Tag, das einer neuen API-Version entspricht, läuft ein Job, der die archivierte Vorversion der OpenAPI-Spezifikation gegen die aktuelle vergleicht, daraus per oasdiff changelog die strukturierten Einträge erzeugt, diese in Markdown rendert und als Entwurf-Pull-Request gegen einen dedizierten CHANGELOG.md-Branch öffnet. Ein Reviewer bearbeitet diesen Pull Request redaktionell, statt bei null anzufangen, und mergt ihn erst nach der Überarbeitung.

Dieser Ablauf hat einen angenehmen Nebeneffekt: Weil der Changelog-Entwurf bereits vor dem eigentlichen Release existiert, fällt einem Reviewer beim Durchgehen oft auf, wenn eine Änderung eigentlich gar nicht so harmlos ist, wie sie im Code-Review erschien, etwa weil sie in der zusammengefassten Übersicht plötzlich als Breaking Change markiert auftaucht. Der Changelog wird damit nicht nur zu einem Kommunikationsmittel für Consumer, sondern zusätzlich zu einer letzten Kontrollinstanz vor der Veröffentlichung, die strukturelle Überraschungen sichtbar macht, bevor sie in Produktion Schaden anrichten.

9. Format und Verteilung des fertigen Changelogs

Der finale Changelog sollte in mehreren Formaten gleichzeitig existieren, weil unterschiedliche Consumer unterschiedliche Zugriffswege bevorzugen. Eine CHANGELOG.md-Datei im Repository dient internen Entwicklern und lässt sich direkt in Pull Requests verlinken, während eine öffentlich erreichbare Version, etwa als eigener Endpoint GET /api/changelog im JSON-Format, es externen Partnern erlaubt, Änderungen automatisiert zu überwachen und etwa bei einem neuen Breaking Change automatisch eine interne Benachrichtigung auszulösen. Ein zusätzlicher RSS- oder Atom-Feed erreicht Entwickler, die den Changelog in ihren gewohnten Feed-Reader einbinden möchten, ohne die Dokumentationsseite regelmäßig manuell zu besuchen.

Für die meisten Symfony-Projekte reicht es, den bereits als Markdown vorliegenden Changelog über ein einfaches Controller-Action als JSON auszuliefern, das die Markdown-Datei parst und in strukturierte Einträge mit Datum, Version und Kategorie zerlegt. Wichtig ist dabei, den Changelog konsequent nach Versionsnummer zu sortieren und alte Einträge nicht zu löschen, denn gerade Teams, die ein Upgrade über mehrere Versionen hinweg nachvollziehen müssen, sind auf eine luckenlose Historie angewiesen, um alle relevanten Breaking Changes zwischen ihrer aktuellen und der Zielversion zu identifizieren.

10. Zusammenfassung

11. FAQ: API-Changelog aus OpenAPI-Diffs: Das Wichtigste auf einen Blick