API-Dokumentation mit Beispielen, die in der CI ausgeführt werden

Ziel

Dokumentation, deren Beispiele nicht von der API abweichen können, weil dieselben Beispieldateien validiert, ausgeführt und gerendert werden.

Voraussetzungen

Ein OpenAPI-Dokument, das als Vertrag dient; eine Sandbox oder ein Testserver mit stabilen Seed-Daten; eine CI-Pipeline im API-Repository. Die zitierte OpenAPI-3.1-Spezifikation definiert Example Objects mit entweder einem value oder einem externalValue, erwartet, dass jedes Beispiel mit seinem Schema verträglich ist, und besagt, dass Tooling diese Verträglichkeit automatisch prüfen und unverträgliche Beispiele zurückweisen kann. Pythons doctest (zitiert) zeigt die zugrunde liegende Idee: Text, der wie eine interaktive Sitzung aussieht, wird ausgeführt und darauf geprüft, dass er genau wie dargestellt funktioniert; rustdoc (zitiert) führt Dokumentationsbeispiele ebenfalls als Tests aus.

Schritte

1. Pro Operation und pro dokumentiertem Fehler ein Beispiel schreiben, als Dateien, die im OpenAPI-Dokument über externalValue referenziert werden, oder als benannte examples-Einträge; jedes nach seinem Szenario benennen (create-order-missing-address).
2. Jedes Beispiel in der CI gegen sein Anfrage- oder Antwortschema validieren; den Build bei Abweichung scheitern lassen.
3. Die Anfragebeispiele in der CI gegen die Sandbox ausführen. Die tatsächliche Antwort mit dem dokumentierten Antwortbeispiel vergleichen, dabei als volatil deklarierte Felder (IDs, Zeitstempel) ignorieren und bei allem anderen scheitern.
4. Die Dokumentation aus denselben Dateien rendern: Referenzseiten, der Schnelleinstieg und SDK-Codeschnipsel binden die Beispieldateien ein, statt eingefügte Kopien zu enthalten.
5. Für Codebeispiele in mehreren Sprachen diese mit je einer Vorlage pro Sprache aus den Beispielen erzeugen und jedes gegen die Sandbox ausführen; ein nicht ausgeführtes Beispiel ist eine eingefügte Kopie und wird abdriften.
6. Wenn ein Beispiel nach einer API-Änderung fehlschlägt, explizit entscheiden: Entweder ist die Änderung ein Fehler, oder Beispiel und Fliesstext ändern sich im selben Commit wie die API.
7. Das Datum der letzten CI-Prüfung auf der Dokumentationsseite anzeigen, damit Lesende eine gepflegte Seite von einer veralteten unterscheiden können.

Erwartetes Ergebnis

Jedes Beispiel auf der Seite ist seit der letzten API-Änderung gegen einen laufenden Server ausgeführt worden; Lesende und Agenten können eine Anfrage kopieren und erhalten die dokumentierte Antwort.

Grenzen und Prüfbasis

Beispiele decken nur dokumentierte Pfade ab und sind keine Testsuite. Die Seed-Daten der Sandbox müssen stabil sein, sonst wird der Vergleichsschritt zu Rauschen. Das Vorgehen ist ein Vorschlag; es wird keine Verringerung von Dokumentationsfehlern behauptet.