Spring Rest Docs und AsciiDoc: Web-APIs automatisiert dokumentieren

Eine gute Dokumentation ist für Web-APIs entscheidend. Mit Spring Rest Docs und Ascii Doc klappt das auch automatisiert. Wir zeigen, wie.

21. November 2025 um 13:30 Uhr / Eine Anleitung von Christoph Huber

Spring Rest Docs und Asciidoc haben viele Vorteile, sind aber auf Java und JVM-Sprachen wie Kotlin beschränkt. Bild: Markus Spiske/Pexels

Die Dokumentation von Web-APIs ist aufwändig und fehleranfällig. Änderungen an den Schnittstellen müssen unbedingt in der Dokumentation nachgezogen werden, ansonsten ist die API für den Konsumenten unbrauchbar. Eine Lösung für dieses Problem ist die Teilautomatisierung der Schnittstellendokumentation. Dabei wird oft ein OpenAPI-Generator eingesetzt, der den Quellcode analysiert und eine OpenAPI-Beschreibung der Schnittstellen erstellt. OpenAPI ist ein verbreiteter Standard zur Beschreibung von Schnittstellen, die OpenAPI-Beschreibung lässt sich mit Swagger UI darstellen und testen.

In diesem Artikel werden Beispiele aus einer Kotlin-Webapplikation gezeigt, die das Spring-Framework verwendet. Die Applikation stellt eine Portfolio-API zur Verfügung, über die dem Portfolio Dienstleistungen (Services) hinzugefügt werden können.