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