Zum Hauptinhalt springen

Befehlsmenü

Zu einer Seite springen oder den Katalog durchsuchen

KI-Tools & -Skripte

API Change Report: Was bei den Nutzern Ihrer API brechen kann, aus zwei Spezifikationen

Für API-Teams und Agenturen: Ein Skript vergleicht Ihre alte und neue OpenAPI- oder Swagger-Datei nach festen Regeln, und Ihr Agent entwirft einen Bericht über potenziell inkompatible Änderungen, eine Migrationsanleitung, einen Changelog-Eintrag und eine Mitteilung für Integratoren, die Sie prüfen. Bericht darüber, was bei den Nutzern der API zwischen zwei Versionen brechen kann.

$7.00

Das bekommst du: 1 Datei · 76.62 KB · ZIP

Kaufoptionen ansehen

Produktbeschreibung

Beschreibung

Für Backend-Entwickler, API-Teams und Agenturen, die eine neue Version einer HTTP-API ausliefern und denjenigen, die sie aufrufen, mitteilen müssen, was sich geändert hat.

Geben Sie Ihrem Agenten die alte und die neue Beschreibung Ihrer API (OpenAPI 3.x oder Swagger 2.0, JSON oder YAML). Der Agent entwirft einen Änderungsbericht, eine Migrationsanleitung und eine Mitteilung für Integratoren, die Sie vor der Veröffentlichung prüfen.

Der Bericht listet potenziell inkompatible Änderungen auf, die durch den Vergleich der beiden Dateien gefunden wurden. Er ist ein Ausgangspunkt für die Prüfung durch Ihr Team, keine bestätigte Kompatibilitätsbewertung.

Ein mitgeliefertes Skript vergleicht die beiden Dateien und stuft jeden Unterschied nach festen Regeln ein. Der Agent schreibt dann, was jede Änderung für einen Client bedeutet: was er sieht und was er ändern muss.

Was der Agent bei jedem Durchlauf schreibt

  • changes.json und changes.csv: jeder Unterschied mit ID, Klasse (inkompatibel, potenziell inkompatibel, kompatibel, nur Dokumentation), Art, Methode und Pfad sowie altem und neuem Wert.
  • change-report.md und change-report.html: die Zusammenfassung mit Zahlen, dann zuerst die inkompatiblen Änderungen, jeweils mit Fundstelle, Änderung, dem, was ein Client sieht, und dem, was zu ändern ist. Das HTML ist eine druckbare Seite ohne externe Dateien.
  • migration-guide.md: Schritte für die Entwickler, die die API aufrufen, mit Vorher-nachher-Ausschnitten aus den beiden Dateien.
  • changelog-entry.md: ein Changelog-Eintrag und ein vorgeschlagener Versionssprung mit Begründung. Das Team entscheidet.
  • consumer-notice.md: eine kurze, sachliche Ankündigung für Integratoren.
  • notes.md: was verglichen wurde, was ein Vergleich zweier Dateien nicht zeigen kann und was einer Entscheidung bedarf.

Regeln statt Vermutungen

Das Skript kennt 118 Arten von Änderungen in vier Klassen, mit getrennten Regeln für das, was ein Client sendet, und das, was er empfängt: Ein neues Pflichtfeld in der Anfrage ist inkompatibel, ein neues Feld in der Antwort nicht. Es folgt lokalen $refs. Führen Sie api_diff.py rules aus, um jede Regel zu lesen. check bestätigt anschließend, dass jede inkompatible ID im Bericht und in der Anleitung abgedeckt ist.

Nur Ihre Fakten

Der Skill weist den Agenten an, Ausschnitte, Pfade und Werte aus Ihren beiden Dateien zu übernehmen und das, was Sie nicht geliefert haben, etwa ein Abschaltdatum der alten Version, als [NEEDS: ...] zu markieren, statt es zu erfinden.

Ehrlich über die Grenzen

Es vergleicht zwei Dateien. Es ruft Ihre API nicht auf, daher liegt Verhalten, das die Beschreibung nicht nennt, außerhalb seines Blickfelds. Die Klassen ergeben sich aus Regeln und sind von Ihrem Team zu bestätigen. Nur lokale $refs werden verfolgt: Eine auf mehrere Dateien verteilte Spezifikation führt zu einer Warnung und einem unvollständigen Vergleich. Der YAML-Leser deckt die gängige Teilmenge ab und nennt die Zeile, wenn er auf etwas anderes stößt (wandeln Sie diese Datei in JSON um). Reguläre Ausdrücke und oneOf / anyOf werden als geändert gemeldet, ohne ausgewertet zu werden. Antwort-Header, Links, Callbacks und Webhooks werden nicht verglichen. Ohne Spezifikation kann der Agent eine einfache Endpunktliste vergleichen, die er aus Ihren Routen-Dateien erstellt; dieser Weg ist schwächer und wurde beim Testen nicht durchgängig ausgeführt. Die HTML-Seite wurde durch Lesen des Quelltexts geprüft, nicht in einem Browser.

Arabisch

Auf Wunsch werden der Bericht, die Anleitung und die Mitteilung auf Arabisch geschrieben, und die HTML-Seite wird von rechts nach links gesetzt, wobei Pfade und JSON von links nach rechts bleiben.

Im Download: SKILL.md, vier Python-Skripte mit Standardbibliothek, Referenzen (die Regeln, wie jeder Eintrag zu schreiben ist, Eingabeformate, Hinweise zu Arabisch), Vorlagen und ein ausgearbeitetes Beispiel, das Sie vor dem Kauf lesen können: eine Zahlungs-API von 1.8.0 auf 2.0.0 mit 75 Unterschieden, gruppiert zu 11 inkompatiblen Einträgen.

Getestet an zwei Fällen (einer Zahlungs-API in OpenAPI 3 YAML auf Englisch; einer Klinik-API in Swagger 2.0 JSON mit arabischem Bericht). Die Skripte haben 85 Unit-Tests.

Kurzfassung

Für Backend-Entwickler und API-Teams, die eine neue Version veröffentlichen und deren Nutzern mitteilen müssen, was sich geändert hat.

Geben Sie Ihrem Agenten die Beschreibungsdatei der alten Version und die der neuen Version (OpenAPI 3 oder Swagger 2, als JSON oder YAML). Er schreibt Ihnen Entwürfe des Änderungsberichts, der Migrationsanleitung und einer Mitteilung für Entwickler, die Sie vor der Veröffentlichung prüfen.

Was der Agent schreibt

  • Die Dateien changes.json und changes.csv: jeder Unterschied mit Nummer, Klasse, Fundstelle sowie altem und neuem Wert.
  • Die Datei change-report: zuerst die inkompatiblen Änderungen, und zu jeder, was der Client sieht und was er ändern muss.
  • Die Datei migration-guide.md: Migrationsschritte mit Vorher-nachher-Ausschnitten aus Ihren Dateien.
  • Die Dateien changelog-entry.md und consumer-notice.md: der Changelog-Eintrag und eine kurze Mitteilung.

Grenzen

Die Ergebnisse sind Änderungen, die möglicherweise inkompatibel sind und die Prüfung durch Ihr Team brauchen. Der Skill vergleicht zwei Dateien und ruft die API nicht auf, daher sieht er nicht, was die Beschreibung nicht nennt. Die Einstufung beruht auf festen Regeln und wird von Ihrem Team bestätigt. Es werden nur Verweise innerhalb derselben Datei verfolgt. Der Bericht kann auf Arabisch mit einer Seite von rechts nach links angefordert werden; das wurde an einem Testfall ausprobiert.

Fragen

Welche Formate liest es?

OpenAPI 3.x und Swagger 2.0, als JSON oder YAML. Der YAML-Leser deckt die gängige Teilmenge ab und nennt die Zeile, wenn er auf eine nicht unterstützte Funktion stößt; wandeln Sie diese Datei in JSON um.

Ruft es meine API auf?

Nein. Es vergleicht zwei Dateien auf Ihrer Festplatte. Verhalten, das die Beschreibung nicht nennt, liegt außerhalb seines Blickfelds.

Wie entscheidet es, was inkompatibel ist?

Nach festen Regeln, die Sie mit dem Befehl rules lesen können: 118 Arten von Änderungen in vier Klassen, mit getrennten Regeln für das, was ein Client sendet, und das, was er empfängt. Ihr Team bestätigt die Klassen.

Was ist, wenn meine Spezifikation auf mehrere Dateien verteilt ist?

Es werden nur Verweise innerhalb derselben Datei verfolgt. Bündeln Sie die Spezifikation zuerst in einer Datei, sonst erhalten Sie eine Warnung und einen unvollständigen Vergleich.

Erfindet es ein Abschaltdatum?

Der Skill weist den Agenten an, das nicht zu tun. Daten und Zeitpläne, die Sie nicht geliefert haben, werden mit [NEEDS: ...] markiert, damit Sie sie ergänzen.

Kann der Bericht auf Arabisch sein?

Ja, als zusätzliche Option, mit einer HTML-Seite von rechts nach links und Pfaden, die von links nach rechts bleiben. Es wurde an einem Testfall ausprobiert; lesen Sie den Bericht vor der Veröffentlichung.

Das bekommst du

1 Datei · 76.62 KB

  • api-change-report-1.0.0.zipZIP · 76.62 KB
LizenzKommerzielle Nutzung erlaubt
PaketprüfungBestanden

Getly hat die hochgeladenen Dateien geöffnet und nichts gefunden, was das Öffnen verhindern würde. Das ist kein Virenscan und keine Qualitätsbewertung.

Veröffentlicht14. Nov. 2026
Dateigröße76.62 KB
DateiformatZIP
Versionv1.0

Tags

openapiswaggerapi diffbreaking changesmigration guidechangelogapi documentationarabicai agent skill
R
RR HH

Häufige Fragen

Erhalte ich sofort Zugriff?

Ja. Dies ist ein digitales Produkt - du kannst es direkt nach dem Kauf aus deiner Bibliothek herunterladen.

Darf ich es für kommerzielle Projekte nutzen?

Ja. Kommerzielle Nutzung ist erlaubt: im eigenen Business und in dem, was du verkaufst. Die Datei selbst darfst du nicht weiterverkaufen oder verbreiten.

Wie sind die Rückerstattungsbedingungen?

Du kannst innerhalb von 30 Tagen eine Rückerstattung anfordern. Stimmt etwas nicht, fordere sie bei deiner Bestellung an - das Getly-Team prüft sie.

Welche Dateiformate und -größen erhalte ich?

Du lädst 1 Datei herunter - ZIP - insgesamt 76.62 KB.

Erhalte ich kostenlose Updates?

Ja - wenn der Verkäufer eine neue Version veröffentlicht, kannst du die aktuellen Dateien kostenlos erneut aus deiner Bibliothek herunterladen. Aktuelle Änderungen findest du im Changelog.

Preis

$7.00