Für die heute dominierenden REST-APIs braucht man eine Möglichkeit, die technischen Schnittstellen so zu definieren, das anbietende und aufrufende Systeme sie schnell verstehen können. Als De-facto-Standard hat sich aktuell Swagger etabliert: Swagger: Mehr als nur Schnittstellenbeschreibung.
Damit dokumentiere ich in meinem aktuellen Projekt auch eine REST-Schnittstelle und die Mächtigkeit hat mich schon beeindruckt. Swagger kann z.B. ohne großen Aufwand eine komplette Weboberfläche mit der API-Dokumentation erstellen, über die sogar jeder Service direkt aus dem Browser heraus aufrufbar und damit testbar ist. Das sieht wirklich ziemlich cool aus und erzeugt beim Programmierer auch nur wenig Aufwand. In unserem Java-Projekt musste ich nur wenige Zeilen Code schreiben und der Rest passierte automatisch. Als plattformunabhängige Schnittstellenbeschreibung setze ich in Zukunft also auf Swagger.
Hast du auch schon einmal eine REST-Schnittstelle entwickelt? Wie hast du sie dokumentiert? Nutzt du auch Swagger oder kannst du noch andere Werkzeuge empfehlen?