Die Entwicklung und Pflege von API-Dokumentationen stellt für Softwareprojekte oft eine große Herausforderung dar. API-Spezifikationen ändern sich regelmäßig, und die Dokumentation muss stets aktuell, verständlich und zugänglich sein. Dank der rasanten Fortschritte im Bereich der Künstlichen Intelligenz (KI) eröffnen sich neue Möglichkeiten, diesen Prozess zu automatisieren und zu verbessern. Ein besonders spannender Ansatz zeigt sich in der Kombination von OpenAPI, dem Qwen-Sprachmodell von Ollama, sowie den Frameworks Quarkus und LangChain4j. Diese Technologien ermöglichen eine dynamische, KI-gestützte Generierung von API-Dokumentationen, die sowohl in der Entwicklererfahrung als auch in der Betriebseffizienz neue Maßstäbe setzen.
Quarkus hat sich als leichtgewichtiges, Cloud-natives Java-Framework etabliert, das speziell für Developer Experience und schnelle Entwicklungszyklen optimiert wurde. Durch die Unterstützung von MicroProfile OpenAPI und kleinen REST-Endpunkten lassen sich APIs schnell implementieren und automatisch mit Metadaten anreichern, die dann in OpenAPI-konformer Form exportiert werden. Diese strukturierte Spezifikation dient als perfekte Basis für den KI-gestützten Dokumentationsprozess. Die Integration von LangChain4j bietet die Schnittstelle, um Large Language Models (LLMs) auf der JVM zu nutzen und direkt mit Quarkus-Services zu verknüpfen. Dadurch werden KI-Aufgaben wie die Generierung von verständlichen, gut strukturierten Texten aus technischen Eingaben sehr einfach.
Ollama stellt Qwen bereit, ein modernes, lokal ausführbares LLM-Modell, das sich ideal eignet, um aus der OpenAPI-Spezifikation hochwertige technische Dokumente zu erzeugen. Die Kommunikation mit dem Modell erfolgt dabei über eine klar definierte Schnittstelle, die mit Hilfe von Annotationen wie @RegisterAiService und @SystemMessage das Verhalten des Bots steuert und die Qualität der Dokumentation präzise beeinflusst. Der Aufbau eines einfachen Beispielprojekts verdeutlicht den praxisnahen Einsatz. Ein Quarkus-Projekt wird mit den Extensions für REST-Jackson, SmallRye OpenAPI, LangChain4j-Ollama sowie dem Jackson-Databind erstellt. In der Anwendung wird eine Produkt-API modelliert, die Produkte listet, im Detail abruft und neue Produkte anlegt.
Durch die Annotationen mit MicroProfile OpenAPI werden Schema und Endpunkte vollständig beschrieben. Quarkus generiert automatisch eine OpenAPI-Spezifikation, die unter /q/openapi im YAML- oder JSON-Format abrufbar ist. Die zentrale Innovation liegt darin, dass man diese live generierte OpenAPI-Spezifikation an das Qwen-Modell übergibt, das daraus in Echtzeit eine ansprechende Markdown-Dokumentation erzeugt. Diese kann dann auf einer Webseite angezeigt oder als Textdatei ausgeliefert werden. Dadurch wird der manuelle Aufwand erheblich reduziert, Fehlerquellen werden minimiert und Dokumentation bleibt stets synchron mit dem Code.
Quarkus Cache sorgt dafür, dass die Dokumente nach der ersten Generierung zwischengespeichert werden, was Performancevorteile in der Entwicklungszeit bringt. Das Prinzip der dynamischen Dokumentation wird dabei mit einem REST-Client umgesetzt, der die OpenAPI-Daten abruft, und einem Service-Interface, das den KI-Text generiert. Die promptbasierte Steuerung der KI ist essenziell, um gute Ergebnisse zu erhalten: So wird Qwen als technischer Redakteur mit klaren Instruktionen positioniert, der verständlich, ausführlich und mit praktischen Beispielen dokumentiert. Entwickler können die Prompts jederzeit verfeinern, um spezifische Bereiche oder unterschiedliche Stile zu erzielen, etwa formell technisch oder eher locker erläutert. Darüber hinaus ist die lokale Ausführung von Qwen über Ollama ein großer Vorteil, da keine Daten an externe Cloud-Dienste gesendet werden müssen, was Datenschutz und Betriebssicherheit erhöht.
Die Nutzung von Dev Services Containern in Quarkus erleichtert zudem die Einrichtung und macht die Umgebung reproduzierbar. Ein weiterer praktischer Schritt ist die Einbindung einer einfachen HTML-Seite im Projekt, die mithilfe von JavaScript und Bibliotheken wie Marked.js die generierte Markdown-Dokumentation in ansprechendes HTML rendert. Damit erhalten Entwickler sofort eine benutzerfreundliche Ansicht, die auf Veränderungen der API reagiert und so stets aktuell bleibt. Für Produktionsszenarien empfiehlt es sich, den Prozess der Dokumentationserstellung in Builds oder CI/CD-Pipelines vorzuziehen.
So lassen sich hohe Latenzen und Laufzeitabhängigkeiten von LLMs vermeiden, und die Dokumentation ist als statische Ressource verfügbar. Zugleich sind Sicherheit und Zugriffsrechte auf die API-Dokumentation besser kontrollierbar. Die Flexibilität der eingesetzten Technologien ermöglicht darüber hinaus zahlreiche Erweiterungen: Ob das Ausprobieren größerer Qwen-Modelle für komplexere Texte, eine stärkere Spezialisierung der Prompts mit zusätzlichen Abschnitten und Codebeispielen bis hin zur Integration mit weiteren Tools aus dem KI-Ökosystem – die Möglichkeiten wachsen mit den Anforderungen der Entwickler und dem Fortschritt der Technologie. Zusammenfassend bietet der Einsatz von OpenAPI mit dem Qwen-Modell in Verbindung mit Quarkus und LangChain4j eine leistungsstarke Basis für automatisierte, klare und stets aktuelle API-Dokumentationen. Der Workflow vereinfacht die Entwicklerarbeit deutlich, steigert die Produktivität und sorgt dafür, dass technische Informationen dauerhaft verständlich vermittelt werden.
