Dokumentation leicht gemacht: Spring REST Docs 1.0.0 RC1 veröffentlicht

Michael Thomas

© Shutterstock.com/Jacob Lund

Das Schreiben von qualitativ hochwertigen und gleichzeitig verständlichen RESTful Services-Dokumentationen ist keine leichte Aufgabe. Das Projekt Spring REST Docs möchte der insgesamt wenig geliebten Arbeit mithilfe eines testgetriebenen Ansatzes ein wenig den Schrecken nehmen.

Bei Spring REST Docs handelt es sich um ein offizielles Spring-Projekt, das den User bei der Erstellung einer präzisen und lesbaren REST-Dokumentation unterstützen soll, wobei es sich in die Spring MVC Test Library einklinkt. Die Idee dahinter: Für jede Ressource wird ein Test geschrieben, der die zu erwartende Kombination aus Request und Response beschreibt. Treffen beide zu, wird automatisch eine Dokumentation im Asciidoctor-Format ausgegeben, die bei Bedarf um händisch erstellte Inhalte ergänzt werden kann. Die Dokumentation lehnt sich somit stark an reale Anwendungsfälle an, ähnelt GitHubs API-Dokumentation und grenzt sich von vollautomatisierten Dokumentationen, wie sie beispielsweise anhand von Tools wie Swagger erstellt werden können, ab.

Seit kurzem liegt für Spring REST Docs ein erster Release Candidate vor, der die Dokumentation von Pfadparametern, Multipart-Requests, und von per Bean Validation API deklarierten Constraints unterstützt und darüber hinaus eine bessere Erweiterbarkeit und Konfigurierbarkeit (z. B. Template-basiertes Snippet-Rendering) bieten soll. Mit der finalen Version von Spring REST Docs kann der aktuellen Roadmap zufolge Anfang Oktober gerechnet werden.

Eine interessante, allgemein gehaltene Einführung in das Thema RESTful-API-Dokumentation bietet das Webinar „Documenting RESTful APIs“ von Andy Wilkinson.

Aufmacherbild: High angle view of an young brunette working at her office desk with documents and laptop. Businesswoman working on paperwork von Shutterstock / Urheberrecht: Jacob Lund

Verwandte Themen:

Geschrieben von
Michael Thomas
Michael Thomas
Michael Thomas studierte Erziehungswissenschaft an der Johannes Gutenberg-Universität Mainz und arbeitet seit 2013 als Freelance-Autor bei JAXenter.de. Kontakt: mthomas[at]sandsmedia.com
Kommentare

Hinterlasse einen Kommentar

avatar
4000
  Subscribe  
Benachrichtige mich zu: