Spring Boot, Apache Camel und Swagger UI

Unternehmen besitzen in der Regel eine Vielzahl von Systemen, die in verschiedenster Weise miteinander kommunizieren müssen. Um das zu bewerkstelligen kommt meistens ein Enterprise Service Bus oder ein Integration Framework zum Einsatz. Ich persönlich bin ein großer Fan von leichtgewichtiger Integration und Flexibilität. Es ist also nicht verwunderlich, dass mein Mittel der Wahl meistens Apache Camel ist. Apache Camel ist ein Integration Framework und kann entweder standalone in Form eines Java jars oder aber als Teil einer Runtime wie zum Beispiel Spring Boot oder WildFly/WildFly Swarm verwendet werden. In diesem Blogpost habe ich mich für Spring Boot entschieden, weil es weit verbreitet ist und mit einer Menge nützlicher Dinge daherkommt, die die Arbeit erleichtern. Zusätzlich zu Spring Boot verwende ich Swagger UI, um eine anwenderfreundliche Dokumentation meiner Schnittstelle zu bekommen. Mit Hilfe dieser Integrationslösungen können mehrere Systeme miteinander verbunden werden. Das geschieht oftmals mittels HTTP. Um diese Integration so einfach und anwenderfreundlich wie möglich zu gestalten, empfiehlt es sich, die HTTP- bzw. REST-Schnittstelle zu dokumentieren.

Dieser Blogpost beschreibt wie diese Technologien miteinander kombiniert werden und wie aus eine Apache Camel REST API automatisiert eine Swagger-UI-Dokumentation erstellt wird. Falls du direkt den Code sehen möchtest, hier der Link zu meinem GitHub Repository.

Erstellen eines Spring Boot Projekts mit Apache Camel

Als erstes wird ein Spring-Boot-Projekt angelegt, das die Apache Camel Dependency enthält. Am einfachsten geht das mit Hilfe des Spring Initializr: https://start.spring.io/

Dort einfach die Group und Artifact Id ändern und anschließend die Apache Camel starter dependency hinzufügen. Ein abschließender Klick auf Generate Project und das Projekt ist lauffähig.

Integrieren von Swagger UI in Spring Boot

Nachdem zuvor das Projekt erstellt wurde, werden nun die Swagger-UI-Dateien hinzugefügt. Dafür müssen die Dateien als erstes heruntergeladen werden: https://github.com/swagger-api/swagger-ui .

Hinweis: Ich verwende Swagger UI in der Version 2.2.8 anstelle des letzten Releases, da die Apache Camel component derzeit noch eine ältere Swagger bzw. Open API Spezifikation unterstützt, die in den neusten Swagger UI releases nicht mehr unterstützt wird.

Swagger UI ist jetzt heruntergeladen. Nun müssen wir ein neues Verzeichnis unter src/main/resources in unserem Projekt anlegen. Dieses Verzeichnis muss einen der folgenden Namen haben, um von Spring Boot als statischer Inhalt veröffentlicht zu werden: static, public oder resources. Anschließend fügen wir den Inhalt des dist-Verzeichnisses von Swagger UI in unser erstelltes Verzeichnis.

Nach diesen Schritten können wir das Projekt starten und sehen unsere Swagger-UI-Seite auf: http://localhost:8080/swagger/index.html

Hinzufügen einer Camel Route

Jetzt ist es Zeit, eine einfache Camel-Route zum Projekt hinzuzufügen. Dazu wird zuerst ein Camel Servlet hinzugefügt.

Dieses Code Snippet fügt ein Servlet Mapping hinzu. Dieses Mapping ist der Prefix für alle Camel-Routen, die wir später hinzufügen werden. Zu erreichen ist das Servlet unter: http://localhost:8080/api/*. Im Anschluss an das Serlvet Mapping kann nun endlich die Route selbst hinzugefügt werden:

Kombinieren von Swagger und Camel-Routen

Bisher sind Swagger UI und die Camel-Route noch nicht miteinander kombiniert. Swagger UI generiert noch keine Dokumentation für die Camel-Routen. Um das zu erreichen ändern wir einfach die URL in der index.html Datei von Swagger UI auf /api-doc/camel-1:

Das war’s schon. Von nun an zeigt uns Swagger UI eine schöne Dokumentation für unsere Camel-Routen an.

Viel Spaß beim Ausprobieren! 🙂