Aufhören, Dokumentation zu schreiben: Wie KI automatisch Ihr API-Schema aus Live-Daten generiert

Das altbekannte Entwicklerproblem — “die Dokumentation ist wieder veraltet” — findet endlich eine Lösung. Nicht durch bessere Disziplin oder strengere Prozesse, sondern durch einen grundlegenden Wandel in der Art, wie Dokumentation überhaupt erstellt wird.

Wir bewegen uns vom Schreiben von Dokumenten hin zu Beobachtung ihrer Entstehung.

---

Die Dokumentationskrise ist real, und die Zahlen belegen es

API-Dokumentation war schon immer die unbezahlte technische Schuldenlast von Softwareprojekten. Doch das Ausmaß des Problems ist unübersehbar.

Postmans State of the API 2025-Bericht befragte Tausende Entwickler und ergab, dass 93 % der API-Teams Kollaborationsblockaden erleben — die häufigste Ursache sind inkonsistente, veraltete oder fehlende Dokumentation. Der Kontext geht verloren, wenn Spezifikationen in Confluence leben, Feedback in Slack erfolgt und Beispiele in persönlichen GitHub-Repos versteckt sind. Das Ergebnis ist eine Schnitzeljagd, wenn jemand verstehen will, was eine API tatsächlich macht.

Die Ausgabe des gleichen Berichts für 2024 zeigt, dass 39 % der Entwickler inkonsistente Dokumente als größte Hürde bei der Arbeit mit APIs nennen, obwohl 58 % der Teams interne Dokumentationstools verwenden. Mit anderen Worten: Die Tools sind vorhanden, aber die Dokumentation zerfällt trotzdem. Und 44 % der Entwickler graben sich direkt durch den Quellcode, um das Verhalten einer API zu verstehen.

Das Problem ist strukturell, nicht motiviert. Entwickler sind nicht faul — sie sind nur schnell. Manuelle Dokumentation kann mit der Geschwindigkeit von CI/CD nicht mithalten.

---

Drei Ansätze, die uns gescheitert sind

Bevor wir zu den funktionierenden Lösungen kommen, ist es wichtig, ehrlich zu sein, was nicht funktioniert hat.

Code-first Annotations — Controller mit @Schema und @ApiResponse Tags zu versehen — hat den Quellcode aufgebläht und eine enge Kopplung zwischen Dokumentationsgenauigkeit und Entwicklerdisziplin geschaffen. Bei Termindruck wurden die Annotations kaum aktualisiert.

Design-first YAML — die OpenAPI-Spezifikation vor dem Code zu schreiben — war architektonisch elegant, aber operativ fragil. Die Spezifikation wurde zum Flaschenhals, und Entwickler lieferten Features, die die Spezifikation nicht abbildete, was zu Drift führte, sobald der Code in Produktion ging.

Postman Collections — gut für Tests, schwach als formale Verträge. Sie waren oft unvollständig, verfehlten Randfälle und fehlten die strukturelle Strenge für automatisierte Client-Generierung oder Compliance-Checks.

Der Postman 2024-Bericht fasst es klar zusammen: “APIs sind nicht mehr nachträglich, sondern das Fundament der Entwicklung, mit zwischen 26 und 50 APIs, die die durchschnittliche Anwendung antreiben.” Dieses API-Umfang kann nicht mehr manuell gepflegt werden.

---

Der Wandel: Von Dokumentation als Aufgabe zu Dokumentation als Beobachtung

Der Ansatz, der 2025 und 2026 echte Aufmerksamkeit gewinnt, ist traffic-basierte API-Dokumentation — die Generierung von OpenAPI- und Postman-Spezifikationen direkt aus Live- oder Pre-Production-Datenverkehr, anstatt aus Entwicklerannotations oder manuell gepflegtem YAML.

Das führende Beispiel in der Produktion ist Levo.ai, das eBPF (Extended Berkeley Packet Filter) nutzt — die gleiche Kernel-Technologie wie Datadog, New Relic, Palo Alto Networks, Cilium und Sysdig — um API-Datenverkehr passiv zu erfassen, ohne Codeänderungen, SDK-Integrationen, Konfigurationsänderungen oder Sidecar-Proxies.

So funktioniert der Prozess:

1. Passives Traffic-Tracking auf Kernel-Ebene

Levo’s eBPF-Sensor wird via Helm Chart für Kubernetes oder einem einzelnen Docker-Befehl für andere Umgebungen installiert. Nach der Installation erfasst es jeden API-Request und -Response, der durch das System läuft — REST, GraphQL, gRPC und SOAP — ohne in den Workflow eingreifen zu müssen und ohne Latenz zu verursachen.

Da eBPF auf Kernel-Ebene arbeitet, ist es sprach- und frameworkunabhängig. Es spielt keine Rolle, ob Ihr Backend Django, Spring Boot oder Express ist. Der Netzwerkverkehr sagt die Wahrheit, egal was.

2. Schema-Inferenz aus beobachteten Payloads

Das System analysiert den erfassten Datenverkehr, um Typen, erforderliche vs. optionale Felder, Authentifizierungsschemata, Statuscode-Muster und Fehlerstrukturen zu erkennen. Wenn es wiederholt ein Feld wie "created_at": "2026-04-05T14:30:00Z" sieht, erkennt es es als ISO 8601-Datum-Uhrzeit. Bei einem konsistenten usr_-Präfix bei IDs wird dieses Muster erfasst. Mehrfache Beobachtungen desselben Endpunkts ermöglichen es, Felder, die immer erscheinen, von solchen zu unterscheiden, die nur bedingt vorhanden sind.

3. OpenAPI-Spezifikation mit KI-angereichertem Metadata

Sobald genügend Datenverkehr beobachtet wurde, generiert die Plattform eine OpenAPI-konforme Spezifikation, die Endpunktpfade, HTTP-Methoden, Request- und Response-Schemas, Query-Parameter-Typen, Authentifizierungsanforderungen, Ratenbegrenzungsinformationen, Statuscodes und Fehlerbehandlungs-Muster enthält. Laut Levo kann diese Methode die Dokumentationsgenauigkeit um bis zu 95 % im Vergleich zu manuell gepflegten Specs verbessern und den Drift, der bei handgeschriebener Dokumentation häufig auftritt, um 20–30 % verringern.

Wichtig ist, dass menschenlesbare Zusammenfassungen für jeden Endpunkt hinzugefügt werden — nicht nur Feldnamen und Typen, sondern auch Kontext darüber, was der Endpunkt macht und wie er benutzt werden sollte. Das ist Dokumentation, auf die ein Entwickler (oder ein KI-Agent) tatsächlich reagieren kann.

4. PII-Erkennung, bevor Daten das System verlassen

Bevor Payload-Daten analysiert werden, sorgt eine Reinigungs-Schicht dafür, sensible Daten — E-Mails, Kreditkartennummern, Passwörter und andere PII-, PSI- und PHI-Felder — zu identifizieren und zu maskieren. Levo stellt sicher, dass weniger als 1 % Ihrer Daten an die SaaS-Plattform gesendet werden, und keine PII das System verlässt. Nur Metadaten und OpenAPI-Spezifikationen werden übertragen.

---

Anwendungsfall: Entwickler-Laptop

Ein wichtiger Punkt, der oft übersehen wird: Dieser Ansatz funktioniert auch lokal, nicht nur in Produktion oder Staging.

Levo’s Unterstützung für Entwickler-Laptops — in einer kostenlosen Version — ermöglicht es Entwicklern, Docker Compose auf macOS oder Windows zu installieren, ihre lokalen Tests durchzuführen oder ihren API-Client zu verwenden, und OpenAPI-Spezifikationen automatisch im Levo-Dashboard zu generieren. Es sind keine Codeänderungen notwendig.

Das ist wichtig, weil Dokumentation so bereits beim Entwickeln entsteht — vor dem Merge, vor Staging, vor Produktion. Die Spezifikation ist eine Nebenwirkung des Schreibens von Tests, kein separates Ergebnis.

---

Wie die Tool-Landschaft 2026 aussieht

Die traffic-basierte Generierung ist nur eine Herangehensweise, doch das KI-Dokumentations-Ökosystem hat sich deutlich erweitert. Die wichtigsten Tools 2026:

Levo.ai — Die technisch rigoroseste traffic-basierte Lösung. Erkennt Shadow APIs (nicht dokumentierte Endpunkte, die trotzdem Traffic erhalten), Zombie APIs (veraltete Endpunkte, die noch aufgerufen werden) und interne APIs. Integriert mit GitHub, GitLab, Jenkins, Jira, AWS API Gateway, Postman und Burp Suite. Starke Compliance-Unterstützung für PCI, HIPAA und ISO 27001.

Apidog — Design-first Ansatz: API entwerfen, dann automatisch Dokumentation aus der lebenden Spezifikation generieren. Unterstützt REST, GraphQL, WebSocket, gRPC, SOAP und Server-Sent Events. Ersetzt Postman, Swagger Editor, Swagger UI, Stoplight und Mock-Tools in einer Plattform. Kostenfreier Plan; kostenpflichtige Pläne ab $12/Benutzer/Monat.

Mintlify — Die bevorzugte Dokumentationsplattform für Unternehmen wie Cursor, Perplexity, Coinbase und Anthropic. KI-nativ mit Git-Sync, WYSIWYG-Editor, LLM-optimiertem Output via /llms.txt und einem MCP Server-Generator, der API-Dokumente direkt für KI-Codierungsassistenten zugänglich macht. Für Entwickler-Erfahrung optimiert.

Ferndesk — Ein KI-Agent (Fern genannt), der Ihren Code, Support-Tickets, Changelogs und Produktvideos liest, um kontinuierlich Dokumentation zu erstellen und zu aktualisieren. Aktualisiert OpenAPI-Spezifikationen alle 6 Stunden. Wandelt Swagger 2.0 automatisch auf OpenAPI 3.x um.

Knowl.ai — Liest Code direkt aus GitHub, Bitbucket oder GitLab und generiert Dokumentation, die bei Code-Änderungen automatisch aktualisiert wird. Kontinuierlich und integriert in die Codebasis.

---

Die Agenten-Fähigkeit

Es gibt eine Dimension dieses Wandels, die über den Komfort für Entwickler hinausgeht.

Laut Postmans State of the API 2025-Bericht haben 51 % der Organisationen bereits KI-Agenten im Einsatz, weitere 35 % planen dies innerhalb von zwei Jahren. KI-Agenten lesen Dokumentation nicht wie Menschen — sie parsen sie, reasoning über Parameter und führen API-Calls autonom aus, ohne auf menschliche Bestätigung zu warten.

Das verändert die Qualitätsanforderungen an die Dokumentation erheblich. Ein Agent, der mit einer veralteten oder unvollständigen Spezifikation arbeitet, ruft falsche Endpunkte auf, übergibt fehlerhafte Parameter oder verarbeitet Fehlerzustände nicht richtig. Die Spezifikation ist nicht mehr nur Referenz für Menschen — sie ist eine Anweisung für autonome Systeme.

Der Postman 2025-Bericht zeigt, dass 89 % der Entwickler täglich generative KI-Tools nutzen, und 41 % verwenden KI-Tools speziell für die API-Dokumentation. Doch KI-generierte Dokumentation, die auf Quellcode basiert, hängt immer noch von korrekten Annotationen und Aktualität ab. Traffic-basierte Generierung umgeht das vollständig: Die Spezifikation spiegelt wider, was die API in der Praxis macht, nicht, was vor sechs Monaten geschrieben wurde.

Mintlify bringt es auf den Punkt: Die beste API-Dokumentation muss für Menschen überschaubar sein und gleichzeitig maschinenlesbar für Agenten. Tools, die /llms.txt veröffentlichen und MCP-Server für ihre Specs generieren, positionieren APIs so, dass sie von KI-Systemen ebenso natürlich konsumiert werden wie von Entwicklern heute.

---

Was das in der Praxis bedeutet

Der Workflow verschiebt sich von einer Dokumentationsphase hin zu einer, die Dokumentation als emergentes Ergebnis von Entwicklung und Testen betrachtet.

Wenn Sie Ihre Integrationstests ausführen, generiert der Datenverkehr die Spezifikation. Wenn Sie in Produktion gehen, aktualisiert sich die Spezifikation. Wenn Sie eine Endpunkt deprecated haben, der noch Traffic erhält, erkennt das System das — nicht weil jemand daran gedacht hat, eine YAML-Datei zu aktualisieren, sondern weil das Netzwerk die Wahrheit sagt.

Levo schätzt, dass dieser Ansatz 30–50 % der Entwicklerstunden einsparen kann, die bisher für Dokumentationspflege aufgewendet wurden, und die Partner-Onboarding-Zeit um bis zu 40 % verkürzen kann, durch stets aktuelle und präzise Spezifikationen.

Die Dokumentationskrise war nie wirklich ein Aufwandsthema. Es ging immer um Timing: Dokumentation wurde immer nachträglich, von einer anderen Person, in einem anderen Tool, gegen ein sich bewegendes Ziel geschrieben. Traffic-basierte, KI-angereicherte Dokumentationserstellung schließt diese Lücke vollständig.

Die Spezifikation wird zu einer kontinuierlichen Reflexion der Realität — weil sie aus der Realität gebaut wird, nicht aus Erinnerung zusammengestellt.

---

Vergleich: Traditionelle vs. traffic-basierte Dokumentation

Dimension	Traditionell (Manuell/Annotation)	Traffic-basiert (KI-beobachtet)
Aufwand	Hoch — erfordert Entwicklerzeit pro Endpunkt	Nahezu null — generiert aus Test- und Produktionsdatenverkehr
Genauigkeit	Anfällig für Drift; spiegelt Absicht, nicht Verhalten wider	Spiegelt tatsächliches Wire-Verhalten wider
Aktualisierungsfrequenz	Manuell; oft nach Release vergessen	Kontinuierlich — aktualisiert bei jedem Deployment
Shadow API-Abdeckung	Keine	Voll — entdeckt automatisch nicht dokumentierte Endpunkte
PII-Handling	Manuelle Überprüfung notwendig	Automatisches Maskieren vor Schema-Inferenz
Agenten-Kompatibilität	Abhängig von menschlicher Vollständigkeit	Strukturiert, maschinenlesbar bei Generierung
Sicherheitslage	Separater Audit-Prozess	Integriert — erkennt Fehlkonfigurationen out-of-the-box

---

Erste Schritte

Wenn Sie heute mit traffic-basierter Dokumentation experimentieren möchten:

• Levo.ai bietet eine kostenlose Forever-Variante für Entwickler-Laptops. Installieren Sie Docker Compose, führen Sie Ihre lokalen Tests durch oder verwenden Sie Ihren API-Client wie gewohnt, und OpenAPI-Spezifikationen werden automatisch im Levo-Dashboard generiert. Keine Codeänderungen nötig.
• Apidog bietet einen kostenlosen Plan mit vollständigen API-Design-, Test- und Dokumentationsfunktionen für Teams, die einen design-first Ansatz verfolgen.
• Mintlify ist die richtige Wahl, wenn Sie bereits Spezifikationen haben und diese schön veröffentlichen sowie KI-zugänglich machen möchten.

Die Frage ist nicht mehr, ob Ihre Dokumentation automatisiert wird. Es ist, ob Sie den Wandel vornehmen, bevor Ihre API-Dokumentation so weit hinterherhinkt, dass sie zur Last wird.

Aufhören, Dokumente zu schreiben. Beginnen, sie zu beobachten.