Seminararbeit
für das Fach
Aktuelle Technologien zur Entwicklung verteilter Java
Anwendungen
mit dem Thema
Selbstdokumentierende REST-APIs
mit OpenAPI
von
Nikolas Paripovic, Studiengruppe IF6A
3
Inhaltsverzeichnis
1 Einführung ...................................................................................................4 1.1 Thematik .............................................................................................. 4 1.2 Fragestellung ........................................................................................ 5 1.3 Verwendete Methodik ......................................................................... 5
2 Cloud Computing .........................................................................................5 2.1 Microservices ....................................................................................... 5 2.2 Representational State Transfer ........................................................... 6
3 Schnittstellendokumentation ........................................................................7 3.1 Spezifikation und Tools ....................................................................... 7
3.1.1 OpenAPI ....................................................................................... 7 3.1.2 Swagger ........................................................................................ 8
3.2 Contract First ....................................................................................... 8 3.2.1 Definition ...................................................................................... 8 3.2.2 OpenAPI 2.0 ................................................................................. 9 3.2.3 Quellcode-Generierung .............................................................. 12
3.3 Contract Last ...................................................................................... 14 3.3.1 Definition .................................................................................... 14 3.3.2 Springfox .................................................................................... 15
4 Zusammenfassung und Ausblick ...............................................................21 5 Literaturverzeichnis ...................................................................................22
5.1 Internetquellen ................................................................................... 22 5.2 Abbildungen ...................................................................................... 22
4
1 Einführung
1.1 Thematik
Der Bedarf an Software ist seit der Erfindung des Computers kontinuierlich
gestiegen. Heute gibt es kaum einen Lebensbereich, in welchem
Computersoftware keine zentrale Rolle spielt. Doch neben der raschen
Verbreitung von Programmen stieg auch dessen Komplexität. Eine
durchschnittlich große Software wird schon lange nicht mehr nur von einigen
wenigen Personen entwickelt, sondern benötigt ganze Entwicklerteams, welche
mehrere Monate mit einem Projekt beschäftigt sind. Die Menge an Code wird
dadurch unüberschaubar groß. Das hat nicht nur den Nachteil, dass sie damit
kaum von einem Menschen ganzheitlich verstanden werden kann, auch
Änderungen oder Erweiterungen sind nur aufwendig durchführbar.
Moderne Softwareentwicklung hat den Anspruch auf diese Entwicklung
einzugehen und den Entwicklern Methoden und Tools anzubieten, um die
Herausforderung des Fortschritts zu bewältigen. Dabei geht der Trend weg von
monolithischen Anwendungen und hin zu
unabhängigen und frei skalierbaren
Microservices. Die Philosophie dahinter ist
es, ein zu lösendes Problem sinnvoll in
mehreren Applikationen aufzuteilen,
welche jeweils ein Teilproblem lösen. Diese unabhängigen Programme werden
meist auf einem Server angeboten und können sich untereinander nutzen und
unterstützen. Die Dokumentation von diesen Schnittstellen ist dabei von
besonderer Bedeutung, denn auch andere Entwickler sollen die Möglichkeit
haben diese Infrastruktur zu nutzen um Software für die Lösung eigener
Probleme zu entwickeln.
Abb. 1 – Monolith und Microservices
5
1.2 Fragestellung
Diese Arbeit beschäftigt sich mit der Frage, wie die Dokumentation von REST-
Schnittstellen sinnvoll und intuitiv in ein modernes Softwareprojekt integriert
werden kann. Hierfür werden zwei verschiedene Ansätze, dem Contract-First-
und dem Contract-Last-Ansatz, mit den technischen Hintergründen und
konkreten Implementierungsmöglichkeiten gegenübergestellt. Zusätzlich
enthält diese Arbeit eigene Ideen und Impulse, die dabei helfen können,
prinzipientreue Software zu entwickeln.
1.3 Verwendete Methodik
Als konkrete Implementierung eines RESTful-Webservices wird in den
Beispielen jeweils eine durch das Spring-Framework1 gestützte Java-
Anwendung verwendet, da sie als verständlich, einfach und weit verbreitet
gilt.2 Das hier vorgestellte Framework, welches im Contract-Last-Ansatz die
OpenAPI-Spezifikation in der Version 2.0 generiert, heißt Springfox.3 Die
Beispiele dazu wurden aus dem Swagger-Editor entnommen. Außerdem wird
Maven als Build-Tool genutzt, da es ebenfalls im Java-Umfeld sehr beliebt ist.4
2 Cloud Computing
2.1 Microservices
In der modernen Softwarearchitektur werden Microservices als
Architekturmuster immer beliebter. Der entsprechende Markt hat sich in den
letzten Jahren positiv entwickelt und wird voraussichtlich auch in Zukunft
weder stagnieren noch fallen.5 Das liegt vor allem daran, dass viele
1 https://spring.io/ 2 https://jrebel.com/rebellabs/java-tools-and-technologies-landscape-2016/ 3 https://springfox.github.io/springfox/ 4 https://jrebel.com/rebellabs/java-build-tools-part-2-a-decision-makers-comparison-of-maven-gradle-and-ant-ivy/ 5 https://www.marketresearchfuture.com/reports/microservices-architecture-market-3149
6
namenhafte und große Technologieunternehmen wie etwa Netflix, Amazon
oder Twitter6 auf diese Technologie setzen. Generell ist der Ansatz, die
Programmlogik sinnvoll aufzuteilen und klar zu trennen, nicht neu. Das Single
Responsibility Principle empfiehlt, dieses Prinzip generell in jeder
Programmiersprache umzusetzen, wobei dessen Umsetzung unterschiedlich
ausfallen kann. Der eigentliche Fortschritt liegt darin, dass man
Verantwortlichkeit nicht nur auf getrennte Teile innerhalb eines Programms
aufteilt, sondern auf eigenständige Applikationen. Statt Java-Klassen und
–Packages entstehen als Resultat Services, die sprachenunabhängig verwendet
werden können. Somit bietet jeder Microservice einen bestimmten Dienst an
und kann im Gegenzug die Dienste der anderen Microservices nutzen. Es
entsteht ein breites Geflecht an Anwendungen, die sich untereinander
unterstützen und benötigen.
Das hat zum einen den Vorteil, dass die Entwicklung neuer Applikationen Zeit
und Kosten spart, da zu der Lösung des Problems bereits vorhandene Dienste
genutzt werden können. Unter Umständen kann durch eine geschickte
Kombination von bereits vorhandenen Microservices ein ganz neuer
Anwendungsfall umgesetzt werden.
Noch viel wichtiger ist allerdings, dass man jede Applikation frei skalieren,
unabhängig austauschen, warten, entwickeln und veröffentlichen kann. Diese
Art der Modularisierung bietet damit eine hohe Flexibilität in der
Softwareentwicklung, die insbesondere in einem Unternehmen mit großen
Entwicklerteams und komplexen Abhängigkeiten wichtig sind.
2.2 Representational State Transfer
Die Schnittstellen von Microservices treten oft als RESTful APIs auf.
Representational State Transfer (REST) ist ein Entwurfsstil für Dienste, wie sie
aus dem World Wide Web bekannt sind. Dabei hat jede Ressource, also jeder
6 https://smartbear.de/learn/api-design/what-are-microservices/
7
Dienst und jedes Dokument eine eindeutige URL, die in Verbindung mit HTTP
mit verschiedenen Methoden angesprochen werden kann.
RESTful APIs verfolgen deshalb das Prinzip, dass jeder Dienst eine eindeutige
URL erhält, die mit dem HTTP-Protokoll angesprochen werden können. Die
wichtigsten Methodenaufrufe sind GET, um eine Ressource anzufordern,
POST, um einer Ressource eine Unterresource hinzuzufügen und PUT, um
eine Ressource zu erstellen.
3 Schnittstellendokumentation
3.1 Spezifikation und Tools
3.1.1 OpenAPI
Es ist nicht verwunderlich, dass die Dokumentation eine bedeutende Rolle in
der Softwareentwicklung spielt. Tools wie Doxygen oder Javadoc erklären und
spezifizieren Variablen, Methoden und Klassen, sodass andere Entwickler
diese bewusst nutzen, erweitern oder bearbeiten können. Besonders
Microservices benötigen eine Dokumentation, die exakt spezifiziert, welcher
Service angeboten wird und wie dieser aufgerufen werden kann.
Aus dieser Notwendigkeit heraus, entstand 2015 die quelloffene OpenAPI
Initiative7 mit dem Ziel die Beschreibung von REST-APIs zu standardisieren.8
Die Mitglieder dieser Organisation, darunter bekannte Unternehmen wie
PayPal oder Google,9 entwickelten gemeinsam im Jahr 2017 den Standard
3.0.10 Die aktuellste Version ist 3.0.2.11
7 https://www.openapis.org/faq 8 https://www.openapis.org/about 9 https://www.openapis.org/faq 10 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md 11 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md
8
3.1.2 Swagger
Swagger versteht sich heute als Sammlung von verschiedenen Werkzeugen für
die Schnittstellenentwicklung. Um OpenAPI-Spezifikationen zu erzeugen,
kann beispielweise der Swagger-Editor verwendet werden, wohingegen ein
Swagger-Codegen aus einer API-Beschreibung das Gerüst eines
Softwareprojektes generieren kann. Die Swagger UI fungiert als
Visualisierungssoftware und Swagger Inspector bietet ein Test-Framework.
Manche Werkzeuge sind dabei Open-Source, andere sind frei oder
ausschließlich kommerziell erhältlich.12
Oft wird die OpenAPI-Spezifikation als Swagger-Spezifikation bezeichnet,
was daran liegt, dass die OpenAPI Initiative aus der Swagger-Community
hervorgegangen ist und bei Gründung der Name der Spezifikation von
Swagger auf OpenAPI geändert wurde.
3.2 Contract First
3.2.1 Definition
Wenn Software mit dem Contract-First-Ansatz entwickelt wird, liegt der Fokus
zu Beginn der Entwicklung auf der Planung und Integration der Applikationen.
Demnach wird vor der Implementierung grundlegend darüber diskutiert,
welches Subsystem wo und in welcher Form existieren soll, welche Sprache
und Bibliotheken zur Umsetzung verwendet werden sollen und wie das
Geflecht an zu nutzenden Diensten aussehen soll. Dies setzt selbstverständlich
ein hohes Knowhow und ein breites Maß an Disziplin voraus, zahlt sich aber
aus, weil man nach der Planung sehr zügig in die Implementierungsphase
einsteigen kann. Außerdem ist bei dessen Beginn allen beteiligten Entwicklern
klar, wie sie einander nutzen und welche Schnittstellen in welcher Form sie
anzubieten haben.
12 https://swagger.io/about/
9
3.2.2 OpenAPI 2.0
Die Spezifikation selbst ist nicht an eine konkrete Auszeichnungssprache
gebunden, allerdings wird häufig YAML oder JSON genutzt. Der konkrete
Aufbau ist dabei nicht allzu komplex und mehr als eine Beschreibung in einem
bestimmten Format als ein Programmiercode zu verstehen.
Abb. 2 – OpenAPI 2.0 Grundinformationen
Zunächst wird in Zeile 1 die konkrete Spezifikationsversion angegeben. In
diesem Fall wird nur Version 2.0 akzeptiert, da höhere Spezifikationsversionen
aufgrund des geänderten Namens statt swagger das Feld openapi fordern. Im
nachfolgenden Abschnitt info werden generelle Informationen über die
Schnittstelle bzw. das Projekt angegeben. Neben Beschreibung, Version und
Angaben zu Lizenzen können auch Kontaktinformationen hinterlegt werden.
Auch Name und Webseite sind mögliche Felder, welche im Beispiel nicht
aufgeführt sind.
Abb. 3 – OpenAPI 2.0 Serverinformationen
10
Ab Zeile 12 beginnt die technische Beschreibung der Schnittstelle. Der Host
des Webservices in Kombination mit dem Base-Path ergibt somit den fixen
Teil der Adresse, auf dem alle angebotenen Services erreichbar sind.
Zusammen mit den schemes, den verwendbaren Transportprotokollen, ist es in
diesem Beispiel die Adresse http://petstore.swagger.io/v2 bzw.
https://petstore.swagger.io/v2. Die tags sind sind optional und müssen daher
nicht zwingend angegeben werden. Sie helfen allerdings Anfragen zu
gruppieren um eine bessere Übersicht, etwa bei Swagger UI, zu schaffen.
Abb. 4 – OpenAPI 2.0 Serviceinformationen
Ein path-Objekt ist eine Liste mit verschiedenen Pfaden, die die
Einstiegspunkte von Methoden definieren. In diesem Beispiel reagiert die
Applikation auf einen POST-Methodenaufruf unter der Adresse http://
petstore.swagger.io/v2/pet. Außerdem ist mit summary und description
beschrieben, was der Dienst leistet.
Doch nicht nur die Existenz eines Dienstes wird in der Spezifikation
abgebildet, sondern auch konkrete Eingabe- und Ausgabewerte. Mit consumes
11
werden die akzeptierten MMIE-Types13 angegeben, die im Body der HTTP-
Anfrage enthalten sind. Das gleiche gilt für produces, wobei dort die
zurückzugebenen Typen gemeint sind. Im Beispiel nimmt der Service also
JSON- oder XML-Dateien an und gibt ebenfalls JSON oder XML zurück. Eine
andere Möglichkeit über die HTTP-Anfrage Informationen zu verschicken ist
die Nutzung von Parametern, die in der Adresse angegeben werden und sowohl
als optional als auch als erforderlich gekennzeichnet werden können.
Allerdings ist der im Beispiel aufgeführte Parameter body hierbei lediglich der
in der HTTP-Anfrage enthaltene Body und nicht etwa ein Parameter in der
URL. Dies ist in der Umsetzung von OpenAPI 2.0 ungeschickt umgesetzt. Alle
Parameter, die einen anderen Bezeichner haben, werden aber als Adress-
Parameter gesehen.
Zuletzt werden Rückgabecodes in Form von HTML-Codes definiert, die bei
dieser Methode auftreten können. Außerdem gibt das Objekt security die
Möglichkeit der sicheren Autorisierung, um die Services vor ungewünschten
Zugriffen zu schützen.
Abb. 5 – OpenAPI 2.0 Eigene Definitionen
13 Internet Media Type
12
Durch die in Zeile 579 angeführten definitions können analog zur
Objektorientierung, wie man sie aus Programmiersprachen kennt, Objekte oder
Module definiert und referenziert werden. Dies geschieht mit $ref:
"#/definitions/Order“. Das macht vor allem dann Sinn, wenn mehrere
Methoden gleichartige Informationen zurückgeben oder verschiedene
komplexere Daten wiederholt gleiche Daten beinhalten.
Abb. 6 – OpenAPI 2.0 Einschränkungen von Datentypen
Die in dem Beispiel genannten Datentypen (id, name) können neben der
Forderungen nach Datentypen oder –formaten noch weiter eingeschränkt
werden: OpenAPI 2.0 unterstützt Felder wie pattern, maximum, minLength und
noch viele mehr, bei denen es auch sinnvoll ist diese in der Spezifikation
einzusetzen.
3.2.3 Quellcode-Generierung
Auf Basis der OpenAPI-Definition können ohne viel Aufwand ganze Projekte
mit Quellcode erzeugt werden. Dabei werden die Methoden zwar nicht mit
Logik gefüllt, allerdings kann die Projektstruktur, sowie Controller-Klassen mit
Methoden und Eingangs- und Ausgangsparametern generiert werden. Dafür
gibt es generell zwei beliebte Möglichkeiten:
Die erste Möglichkeit ist die Nutzung des Swagger-Editors. Dies empfiehlt
sich vor allem dann, wenn dieses Tool ohnehin dafür benutzt wird, die
Schnittstelle zu schreiben. Außerdem ist die Generierung dank schlanker
Bedienung sehr einfach.
13
Abb. 7 – Swagger-Editor Codegenerierung
Unter Generate Server kann ausgewählt werden, welches Serverpaket generiert
und als ZIP zur Verfügung gestellt werden soll. Für eine einmalige
Generierung ist das eine gute Möglichkeit, da keine Installation notwendig ist
und das von Swagger angebotene Tool quelloffen und kostenlos verwendbar
ist.
Die andere Möglichkeit, Quellcode zu generieren, ist der Swagger-Codegen,
ein anderes, aber genauso quelloffenes Werkzeug von Swagger. Es bietet mit
einem Command-Line-Interface (CLI) die Möglichkeit Projekte mit Skripten
automatisiert zu erzeugen und so den Contract-Last-Ansatz konsequent in den
Workflow zu integrieren. Außerdem können mehr Details angegeben werden,
wie etwa die Einstellung des Maven Artifacts oder der Packages, in der die
Source-Dateien erstellt werden. Es ist allerdings nicht so intuitiv und einfach
zu bedienen.
Abb. 8 – Swagger-Codegen Codegenerierung
14
Mit diesem Kommandozeilenaufruf wird ein Java-Projekt aus einer OpenAPI-
Definition generiert. Dazu wird die swagger-definition.yaml als Input-
Parameter verwendet. Als Implementierungssprache wird Java-Code in
Verbindung mit Spring-Boot generiert (-l spring). Zusätzlich werden Maven-
Informationen angegeben, um die pom.xml sofort richtig initialisiert zu haben.
Das generierte Projekt kann anschließend in eine IDE importiert werden.
Abb. 9 – Eclipse IDE generiertes Projekt
3.3 Contract Last
3.3.1 Definition
Der Contract-Last-Ansatz definiert sich daraus, dass man sich die
Spezifikation, die man beim Contract-First-Ansatz manuell erstellen musste,
Frameworks generieren lässt. Dabei ist die Dokumentation, ähnlich wie bei
Javadoc, fest an den Code gebunden und wird so unumgänglich in den
Workflow integriert. Änderungen an Schnittstellenmethoden können so
umgehend angepasst werden und die Gefahr, die Dokumentation nachzuziehen,
ist deutlich geringer. Dadurch, dass sich die Spezifikation nach Anweisung des
15
Programmierers von selbst auf den neusten Stand bringt, entstehen
selbstdokumentierende Schnittstellen.
3.3.2 Springfox
3.3.2.1 Installation
Als konkrete Bibliothek, die die von OpenAPI vorgeschriebenen Annotationen
erkennt und daraus API-Spezifikationen generiert, ist Springfox weit verbreitet.
Springfox bindet sich intuitiv in das Spring- und Java-Framework ein und ist
leicht zu konfigurieren. Leider unterstützt es derzeit nur OpenAPI 2.0. Eine
Unterstützung von der neusten Version ist aber bereits in Arbeit.14
3.3.2.2 Konfiguration
Um das Framework einzurichten sind grundsätzlich zwei Schritte notwendig.
Zuerst müssen Abhängigkeiten im Build-Tool angegeben werden, die sich
allerdings auf nur zwei wichtige Artefakte reduzieren.
Abb. 10 – Maven Springfox Dependencies
Das erste Artefakt enthält die Logik, aus Annotationen eine OpenAPI
Spezifikation in der Version 2.0 zu generieren. Springfox-swagger-ui hingegen
bietet einen weiteren Dienst an, auf dem man die generierte YAML oder JSON
in einer grafischen Oberfläche betrachten kann. Diese ist meist unter dem Link
http://<host>:<port>/swagger-ui.html erreichbar, wohingegen die generierte
Spezifikation unter http://<host>:<port>/v2/api-docs zu finden ist.
14 https://github.com/springfox/springfox/issues/2022
16
Abb. 11 – Spring Springfox Integration
Anschließend muss eine Konfigurations-Klasse implementiert werden, die
Springfox die benötigten Informationen zum Generieren der Spezifikation
bereitstellt. @Configuration bindet dabei die Klasse an das Spring-Framework
an, während @EnableSwagger2 die Freigabe zum Erkennen von API-
Annotationen gibt. OpenAPI bietet Default-Werte, weshalb die
Vernachlässigung von Lizenz, Kontakt oder Version zu keinem Fehler führt.
3.3.2.3 Dokumentation
Mit Dokumentation versehen werden sollte jede Schnittstelle, also alle
Methoden, die auf REST-Anfragen reagieren. Diese befinden sich in den
jeweiligen Controllern. Außerdem müssen Objekte, die direkt oder indirekt mit
dieser Schnittstelle in Zusammenhang stehen, ebenfalls dokumentiert werden.
Abb. 12 – OpenAPI Klassen Dokumentation
Die Annotation @Api fungiert als eine Art Schalter, mit der Klassen für die
Generierung an und ausgeschaltet werden können. Die nachfolgende Spring-
Annotation definiert alle Methoden in der Klasse als verfügbar unter dem
Unterpfad v1/pet, außerdem reagieren sie auf POST-Anfragen und
konsumieren sowie produzieren JSON-Objekte.
17
Abb. 13 – OpenAPI Methoden Dokumentation
An dieser Stelle offenbaren sich die Stärken einer selbstdokumentierenden
Schnittstelle. Technisch muss man dieser Methode nichts mehr hinzufügen,
denn sie wird so bereits richtig dokumentiert. Durch die Spring-Annotationen
werden Pfad, Anfragemethode, Parameter und Rückgabewert richtig erkannt
und in die Spezifikation geschrieben. Dies funktioniert auch bei POST-
Anfragen, die komplexe JSON-Strukturen im Body an die Applikation
schicken, sowie Rückgabewerte mit Listen oder weiteren Java-Objekten.
Abb. 14 – OpenAPI Methoden Dokumentation erweitert
Eine nur technisch korrekte Spezifikation wird allerdings in der Praxis nicht
gewünscht, da sie wenig detailliert ist und keine Erklärung und Beispiele zu
den einzelnen Methoden bietet. Darum kann die Spezifikation durch weitere
Annotationen vervollständigt werden. Bei @ApiOperation beispielsweise kann
eine Zusammenfassung und ein Beispiel angegeben werden. @ApiResponses
listet alle möglichen HTTP-Codes auf, die der Dienst zurückliefert. Diese
können nämlich nicht automatisiert erkannt werden. Nicht zuletzt können
Parameter mit @ApiParam als optional oder erforderlich definiert werden.
Neben den erwähnten Annotationen gibt es noch einige andere, die allerdings
in der Praxis nicht so häufig vorkommen dürften. Dabei geht es auch um
Authorisierung und anderen Erweiterungen.
18
3.3.2.4 Constraints Plugin
Sowohl in der OpenAPI-Spezifikation als auch in der Annotation-Welt von
Java gibt es Möglichkeiten Datentypen einzuschränken. Leider stellt man fest,
dass Java-Annotationen aus dem javax.validation.constraints Package (etwa
@Size und @Max) nicht in die API-Beschreibung übernommen werden.
Abb. 15 – Maven Springfox Plugin Dependencies
Dieses Plugin ermöglicht es, die Datentypen-Einschränkungen in fast vollem
Umfang zu nutzen. Einschränkungen muss man bei generischen Typen machen
wenn Annotationen innerhalb der spitzen Klammern stehen.
Abb. 16 – Springfox Plugin Integration
Das Plugin ist erst funktionsfähig, wenn es mit @Import in die Spring-
Umgebung eingebunden wurde.
3.3.2.5 Maven Plugin
Versionen von Programmen ändern sich ständig. Besonders im Umfeld von
Microservices, bei denen regelmäßige und schnelle Updates durchgeführt
werden, versucht man, Datenredundanzen zu vermeiden. Es ist deshalb
erstrebenswert Daten, die sich öfter ändern, an exakt einer Stelle zu speichern.
Dazu gehört vor allem die Versionsnummer, die sowohl in der OpenAPI-
Spezifikation, als auch in der pom.xml benötigt wird.
Um die zahlreichen Redundanzen zwischen Maven und Springfox zu umgehen,
empfiehlt es sich eine geschickte Lösung mit Maven-Models umzusetzen.
19
Abb. 17 – Maven Model Dependencies
Abb. 18 – Maven Build Einstellungen
Hierfür muss die pom.xml um die entsprechenden Zeilen ergänzt werden. Der
obere Teil fügt eine Abhängigkeit hinzu, die es ermöglicht, alle Maven-
Eigenschaften als Java-Objekte im Code zu benutzen. Um die Datei beim
Builden mit den wichtigen Informationen importieren zu können, benötigt es
im Maven Build-Prozess das File-Filtering.15 Hierbei wird eine Datei in einem
bestimmten Ordner eingelesen, Umgebungsvariablen hineingeschrieben und im
Build-Verzeichnis abgelegt.
Abb. 19 – Inhalt Datei project.properties
Hierbei ist der Zweck der project.properties dabei nicht, Daten aus der
pom.xml in dem System zur Verfügung zu stellen. Alle Daten sollen
schließlich über Java-Objekte zur Verfügung stehen. Allerdingswerden die
groupId und die artifactId des Projektes dazu gebraucht um die pom.xml
einlesen zu können, da sie zur Laufzeit an einem anderen Ort wie zur
Entwicklerzeit ist. Zur Laufzeit befindet sie sich an dem relativen Pfad META-
INF/maven/<groupId>/<artifactId>/pom.xml.
15 https://maven.apache.org/plugins/maven-resources-plugin/examples/filter.html
20
Abb. 20 – Konkrete Umsetzung Importierung Maven-Daten
Die Methode apiInfo wird beim Start der Anwendung aufgerufen, wenn
Springfox sich konfiguriert und die grundlegenden Informationen der
Anwendungen fordert. Darunter fallen unter anderem der Projektname, die
Version und eine Kontaktperson. Zunächst wird die von Maven ergänzte
project.properties eingelesen und von den zwei Schlüssel-Wert-Paaren der
Wert für die Maven groupId und artifactId zwischengespeichert. Damit kann
der Pfad zu der pom.xml bestimmt werden. Nun wird der mitgelieferte Maven-
Reader genutzt um die Datei zu parsen und in Java-Objekte zu packen.
Ab diesem Zeitpunkt sind alle Daten, die in der pom.xml verfügbar sind, der
Methode durch die Variable model bekannt. Jetzt kann intuitiv und einfach
alles ausgelesen werden, was Springfox fordert: Die Version, der Name, eine
Beschreibung, Lizenzen und eine Kontaktperson.
21
4 Zusammenfassung und Ausblick
Insgesamt kann man nicht sagen, welcher Ansatz besser ist. Am sinnvollsten
ist es daher, beide Ansätze zu kombinieren. Das bedeutet erst eine gut
durchdachte Architektur und Planung aufstellen und dann Code-Generatoren
dafür verwenden, das ideale Startprojekt zu erstellen. Am besten mit einem
Build-Server der im Vorhinein die richtigen Git-Projekte erstellt und sie den
Entwicklern zuweist. Entwickelt sich die Applikation nach der ersten
Veröffentlichung weiter, wird im Code dokumentiert daraus automatisiert
Spezifikation erstellt und diese den Anwendern zur Verfügung gestellt.
Zukünftig wird es mit OpenAPI 3.0 im Vergleich zu Version 2.0 noch
einfacher und intuitiver, Schnittstellen zu beschreiben und zu entwickeln. Viele
Verbesserungen wie etwa das Hinzufügen von mehr Beispieledaten bei
Parametern oder die Möglichkeit, mehrere Server anzugeben, sind durchaus
sinnvoll und erweitern die Spezifikation zukunftsorientiert. Somit ist
sichergestellt, dass Microservices auch in Zukunft im Trend bleiben und sich
dessen Entwicklung mit der Zeit weiterentwickelt und verbessert.
22
5 Literaturverzeichnis
5.1 Internetquellen
1 https://spring.io/, abgerufen am 24.05.19 2 https://jrebel.com/rebellabs/java-tools-and-technologies-landscape-2016/, abgerufen am
24.05.19 3 https://springfox.github.io/springfox/, abgerufen am 24.05.19 4 https://jrebel.com/rebellabs/java-build-tools-part-2-a-decision-makers-comparison-of-maven-
gradle-and-ant-ivy/, abgerufen am 24.05.19
5 https://www.marketresearchfuture.com/reports/microservices-architecture-market-3149,
abgerufen am 24.05.19
6 https://smartbear.de/learn/api-design/what-are-microservices/, abgerufen am 24.05.19
7, 9 https://www.openapis.org/faq, abgerufen am 24.05.19 8,12 https://www.openapis.org/about, abgerufen am 24.05.19 10 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md, abgerufen
am 24.05.19 11 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md, abgerufen am 24.05.19 14 https://github.com/springfox/springfox/issues/2022, abgerufen am 24.05.19 15 https://maven.apache.org/plugins/maven-resources-plugin/examples/filter.html, abgerufen
am 24.05.19
5.2 Abbildungen
Abb. 1 https://martinfowler.com/articles/microservices.html, abgerufen am 24.05.19 Abb. 2 – Abb. 20 Eigene Screenshots