Unklare API-Dokumentation verzögert Integrationstests
Ein Softwareunternehmen mit 3.200 Mitarbeitenden betreibt über 220 Services. Von rund 1.400 API-Dokumenten pro Jahr sind viele bei Projektstart unvollständig und verzögern Integrationen.
- Technologiebranche
- Softwareentwicklung
Leitkennzahl
Zeitaufwand pro API-Dokument
3 h1,5h
Durchschnittlicher Zeitaufwand pro API-Dokument
Auf einen Blick
Ausgangslage
Das Softwareunternehmen betreibt mit rund 3.200 Mitarbeitenden über 220 Services in mehreren Produktlinien. Jährlich werden etwa 1.000 Features umgesetzt, von denen rund 70 Prozent neue oder geänderte APIs betreffen. Pro API entstehen im Schnitt zwei Dokumente für interne und externe Konsumenten, also rund 1.400 API-Dokumente pro Jahr. OpenAPI-Spezifikationen gibt es für die meisten REST-Services, sie werden aber teils von Hand gepflegt und weichen vom Code ab. Die erläuternde Dokumentation pflegen etwa 18 Produktteams in unterschiedlichen Tools, von Wikis über Markdown-Dateien im Repository bis zu PDF-Anhängen. Für jede API-Beschreibung fallen bisher im Mittel drei Stunden für Erfassung, Abstimmung und Nachpflege an, zusammen rund 4.200 Stunden pro Jahr.
- 1.400
- API-Dokumente pro Jahr
- 4.200 h
- Dokumentationsaufwand pro Jahr
Die Herausforderung
Die API-Dokumentation ist häufig unvollständig oder veraltet, sobald Integrationsprojekte starten. Endpunkte sind zwar gelistet, doch Beispiele, Fehlercodes oder Randfälle fehlen. Unterschiedliche Teams verwenden verschiedene Formate und Begriffe, was die Wiederverwendung erschwert. Integrationspartner melden sich mit Rückfragen, weil sie aus der Dokumentation nicht erkennen, welche Felder Pflicht sind oder welche Statuscodes in welchen Situationen auftreten. QA-Teams müssen sich Informationen aus Tickets, Code und alten Dokumenten zusammensuchen. Integrations- und End-to-End-Tests starten verspätet, weil Klarstellungen erst in mehreren Abstimmungsrunden geklärt werden.
Typische Symptome im Unternehmen
Warum das bisher ungelöst blieb
Das Problem war bekannt, wurde aber als unvermeidbare Folge hoher Änderungsgeschwindigkeit akzeptiert. Es existierten zwar Styleguides und ein API-Portal, doch deren Pflege war manuell und zeitaufwendig. Die Generierung aus Code-Kommentaren und OpenAPI-Spezifikationen deckte nur Signaturen und Schemas ab, nicht aber Beispiele, Randfälle oder Integrationshinweise. Ein dediziertes Projekt zur Vereinheitlichung der Dokumentation hätte mehrere Monate Kapazität in Entwicklung und QA gebunden und wurde daher immer wieder zugunsten fachlicher Features verschoben.
Unsere Lösung
Gemeinsam mit den Entwicklungsteams wurde ein Assistenzsystem eingeführt, das die maschinenlesbare Spezifikation zur verbindlichen Quelle macht: OpenAPI für REST-Schnittstellen, AsyncAPI für ereignisbasierte Schnittstellen. Zuerst gleicht das System die Spezifikation mit Code und Tests ab, ergänzt fehlende Angaben und prüft sie per Linting gegen den API-Styleguide. Darauf aufbauend entsteht ein Dokumentationsentwurf mit klaren Abschnitten zu Endpunkten, Parametern, Beispielen, Fehlercodes, Randfällen und Integrationshinweisen. Entwicklerinnen starten aus ihrem gewohnten Workflow, etwa aus dem Repository oder dem API-Portal. Beispielanfragen und -antworten werden gegen Spezifikation und Contract-Tests validiert, bevor sie in einen Entwurf übernommen werden. Das System markiert Unsicherheiten und verweist auf ähnliche bestehende APIs. QA und Integrationspartner geben Feedback, das in neue Versionen einfließt. So entsteht ein einheitlicher Standard, ohne die Teams in ein neues Tool zu zwingen.
Wo generative KI arbeitet
Generative KI analysiert Code, Tests, Commit-Nachrichten, Tickets und bestehende API-Dokumente und formuliert auf Basis der Spezifikation strukturierte API-Beschreibungen mit Beispielen und Fehlerfällen. Sie versteht unstrukturierte Beschreibungen, überträgt Muster aus ähnlichen APIs, benennt Randfälle und offene Fragen und verbessert Entwürfe iterativ mit Feedback. Die Prüfung von Spezifikation und Beispielen bleibt deterministisch und liegt nicht beim Sprachmodell.
- OpenAPI- und AsyncAPI-Spezifikationen als verbindliche Quelle, die aus Code und Tests abgeglichen, ergänzt und per Linting gegen den Styleguide geprüft werden
- Integration in Repositories und API-Portal, um Signaturen, Kommentare und bestehende Beschreibungen automatisch zu übernehmen und zu verknüpfen
- Anbindung an Ticketsystem und Testsuiten, damit relevante User Stories, Akzeptanzkriterien und Testfälle in die Dokumentation einfließen
- Interaktiver Dokumentationsassistent, der fehlende Angaben markiert, gezielt nachfragt und Beispielanfragen vorschlägt, die automatisch gegen Spezifikation und Contract-Tests validiert werden
- Reviewmodus mit rollenbasiertem Zugriff für QA und Integrationspartner, der Kommentare bündelt, Änderungen hervorhebt und Freigaben für veröffentlichte API-Dokumente dokumentiert
- Feedbackschleife, die angenommene und abgelehnte Vorschläge auswertet und damit Prompts, Beispielsammlung und Retrieval an Teamkonventionen anpasst, ohne das Modell neu zu trainieren
Einführung in der API-Entwicklung
Ist-Analyse
Erhebung typischer API-Dokumente, vorhandener OpenAPI-Spezifikationen, Integrationsprozesse und Styleguides in ausgewählten Produktteams, inklusive Zeitaufwänden und Pain Points.
Pilotintegration
Anbindung des Assistenzsystems an Repositories, API-Portal und Ticketsystem für zwei Teams, Definition der Zielstruktur für API-Dokumente und erster Pilotbetrieb.
Feintuning
Gemeinsames Nachschärfen von Gliederung, Tonalität und Beispielsammlung, basierend auf realen Pilotdokumenten und Feedback von QA und Integrationspartnern.
Rollout
Schrittweiser Rollout auf weitere Teams, Schulungen in kurzen Sessions und Anpassung der Freigabeprozesse im API-Portal an den neuen Dokumentationsworkflow.
Monitoring
Laufende Auswertung von Nutzungsrate, Integrationsrückfragen und Qualitätsvorfällen, regelmäßige Anpassung von Prompts, Beispielen und Retrieval an neue Richtlinien und API-Muster.
Gemessen: Nach sechs Monaten Produktivbetrieb
Zeitraum: Nach sechs Monaten Produktivbetrieb.
| Kennzahl | Wert | Basis |
|---|---|---|
| Zeitaufwand pro API-DokumentLeitkennzahl | von 3 Stunden auf 1,5 Stunden je Dokument | Zeitprotokoll in den Pilotteams, vor/nachgemessen |
| Integrationsrückfragen pro API | Reduktion von durchschnittlich 5 auf 3 Rückfragen | Systemmessunggemessen |
| Fehlgeschlagene Integrationstests mit Ursache Doku-FehlerGütemaß | Anteil sinkt von rund 30 % auf 20 % | Stichprobe fehlgeschlagener Testsgeschätzt |
| Nutzungsrate | Rund 75 % der neuen API-Dokumente starten mit einem Entwurf aus dem Assistenten | Systemmessunggemessen |
| Qualitätsvorfälle | 3 fehlerhafte Beispiele in freigegebenen Dokumenten, jeweils innerhalb eines Arbeitstags korrigiert | Eskalationsticketsgemessen |
Wirtschaftlichkeit
Die Lösung entfaltet ihren vollen Nutzen nur, wenn Teams den Assistenten konsequent nutzen und die Spezifikation im API-Portal als zentrale Quelle akzeptieren. Bei sehr kleinen oder kurzlebigen APIs kann der zusätzliche Schritt als Overhead wirken. Einige Bausteine bieten API-Portale und Coding-Assistenten inzwischen als Standardfunktion. Der tatsächliche Aufwand hängt davon ab, wie viel davon sich nutzen lässt.
Integration und Betrieb
Übertragbarkeit
Der Ansatz eignet sich überall dort, wo Schnittstellen oder Produkte regelmäßig dokumentiert werden müssen, aber Inhalte stark variieren und viele Freitexte enthalten. Durch die Kombination aus strukturierten Templates, generativen Entwürfen und integrierten Reviews lassen sich auch in anderen Domänen Dokumentationsprozesse beschleunigen, ohne starre Tools einzuführen. Wichtig ist ein klarer Rahmen, welche Inhalte weiterhin von Menschen geprüft und freigegeben werden müssen.
Ähnlicher Fall im eigenen Haus? Sprechen wir darüber.
Beschreibe kurz deinen Prozess. Wir melden uns mit einer ersten Einschätzung, ob sich das Muster übertragen lässt, und was es realistisch braucht.