JAX - Die OpenAPI Specification alias Swagger: Mehr als nur eine Schnittstellenbeschreibung

JAX Konferenz, Mainz, 26. April 2018

APIs zwischen Systemen wurden in der Vergangenheit häufig in der Web Services Description Language (WSDL) beschrieben. Technisch ist es mit WSDL 2.0 möglich, auch REST-Schnittstellen zu beschreiben, aufgrund fehlender Ressourcenorientierung ist dies jedoch nur bedingt sinnvoll. Die Web Application Description Language (WADL) adressiert dieses Problem, gilt in der Praxis aufgrund der vorliegenden XML-Struktur jedoch als umständlich und wurde nie standardisiert. Stattdessen hat sich Swagger durchgesetzt, eine leichtgewichtige Möglichkeit, um APIs im JSON- bzw. YAML-Format zu definieren. Die Spezifikation wird seit einiger Zeit herstellerneutral unter dem Mantel der Linux Foundation von der Open API Initiative (OAI) weitergetrieben und seitdem unter dem Namen OpenAPI Specification geführt. Neben dem generellen Funktionsumfang werden im Vortrag die Verbesserungen der Version 3 vorgestellt. Am Beispiel in Kombination mit JAX-RS, Apache CXF und Spring Boot wird verdeutlicht, wie einfach sich Schnittstellenbeschreibungen in den Alltag integrieren lassen.

Transcript

1. DIE OPENAPI SPECIFICATION ALIAS SWAGGER MEHR ALS NUR SCHNITTSTELLENBESCHREIBUNG Dennis Kieselhorst | CTS EVENTIM
2. ÜBER MICH über 10 Jahre Erfahrung mit Java und verteilten So warearchitekturen früher Lead Entwickler, Architekt, Consultant bei EWE TEL, T-Systems und IRIAN inzwischen Team Leader und Chief Architect Tixx bei CTS EVENTIM Committer bei der Apache So ware Foundation Mitglied in Organisationskomitees Java User Group (JUG) Bremen-Oldenburg Java Forum Nord
3. AGENDA Schnittstellen/ APIs allgemein Die Geburtsstunde von Swagger Gründung der Open API Initiative API-Entwicklung (Contract/ API vs. Code First) Alternativen zur OpenAPI Specification Praktische Anwendungsbeispiele Unterschiede zwischen Version 2.0 und 3.0.x Fazit
4. SCHNITTSTELLEN Application Programming Interfaces (APIs) früher häufig in der beschrieben mit WSDL 2.0 technisch auch für REST-Schnittstellen möglich aufgrund fehlender Ressourcenorientierung aber nur bedingt sinnvoll ist ressourcenorientiert gilt in der Praxis aufgrund der vorliegenden XML-Struktur aber als umständlich wurde nie standardisiert Web Services Description Language (WSDL) Web Application Description Language (WADL)
5. DIE GEBURTSSTUNDE VON SWAGGER (1/3) 2010 durch Tony Tam ins Leben gerufen, da kein einfaches, unkompliziertes Beschreibungsformat für REST-APIs existierte Verwendung unterschiedlicher Technologien und Programmiersprachen in Kombination mit WSDL und WADL gestaltete sich schwierig Interface Definition Language (IDL) entwickelt und Open Source unter der Apache Lizenz veröffentlicht
6. DIE GEBURTSSTUNDE VON SWAGGER (2/3) Swagger bietet ein sprachneutrales und maschinenlesbares Format, definiert in JSON oder YAML, ermöglicht Contract/ API-First sowie Code-First Entwicklung und verfügt über einen Erweiterungsmechanismus.
7. DIE GEBURTSSTUNDE VON SWAGGER (3/3) Unterstützt wird dies durch grundlegendes Tooling in Form einer Kernbibliothek (swagger-core), einer Oberfläche für Visualisierung und Testaufrufe (swagger- ui), eines Codegenerators (swagger-codegen) sowie sowie eines Editors (swagger-editor).
8. GRÜNDUNG DER OPEN API INITIATIVE (1/2) stetig wachsende Swagger Fan-Gemeinde Kauf von Swagger durch Anfang 2015 Gründung der unter dem Dach der Linux Foundation Ende 2015 herstellerneutral bleiben unterschiedliche Interessen und Verbesserungsvorschläge besser handhaben SmartBear Open API Initiative (OAI)
9. GRÜNDUNG DER OPEN API INITIATIVE (2/2) Im Zuge der Gründung wurde Swagger in OpenAPI Specification (OAS) umbenannt. Inzwischen zählt die Initiative , darunter Google, IBM und Microso . Weiterentwicklung der Spezifikation erfolgt auf GitHub Ende Juli 2017: Veröffentlichung der Dezember 2017: Patch-Release 33 Mitglieder Version 3.0.0 Version 3.0.1
10. API-ENTWICKLUNG Ausgangspunkt für die API-Entwicklung ist entweder die Schnittstellenbeschreibung (Contract/ API-First) oder der erstellte Programmcode (Code First).
11. CONTRACT/ API-FIRST http://editor.swagger.io
12. CONTRACT/ API-FIRST: VORTEILE Schnittstellenbeschreibung als vereinbarten Vertrag bei unterschiedlichen Teams für Client- und Serverseite häufig sogar in unterschiedlichen Unternehmen Client- und Servercode können mit direkt daraus generiert werden. Code ist konsistent zur API Kompilierungsfehler bei Brüchen (durch Continous Integration System wie bspw. Jenkins automatisierbar) (noch nicht released) unterstützt OAS 3 Swagger Codegen Codegen Version 3
13. CONTRACT/ API-FIRST: NACHTEILE Code wird ggf. etwas unübersichtlicher generelle Kritik an spezifikationsbasierter Codegenerierung ( ) besser Tolerant Reader Pattern anwenden hängt von Umfang und Änderungshäufigkeit der API ab und muss im jeweiligen Projekt bewertet werden Technology Radar
14. VISUALISIERUNG DER API Alternativen: (Version 2.0.0-alpha unterstützt OAS 3) und (bislang keine OAS 3 Unterstützung) Swagger UI ReDoc Swagger2Markup
15. CODE FIRST Eigenscha en werden im Code mit Annotations festgelegt im mit Java und JAX-RS (implementiert von und ) bietet vergleichbare Annotations für .NET, PHP und Sprachen gibt es ähnliche Möglichkeiten zur Laufzeit wird aus diesen die Swagger-Beschreibung generiert abrufbar unter /openapi.yaml bzw. /openapi.json (plus ggf. konfiguriertem Pfad) nutzbar bspw. mit und zusätzlich integrierte Swagger UI in (bislang keine OAS 3 Unterstützung) und Swagger Core Annotations Beispiel MicroProfile OpenAPI Open Liberty WildFly Swarm weitere Jersey RESTEasy Springfox Apache CXF
16. CODE FIRST: JAVA ANNOTATIONS @OpenAPIDefinition Metadaten auf Klassenlevel (Info, Server, Tags, Security) @Operation eine einzelne Operation (Pfad und HTTP-Methode), Daten von den JAX-RS Annotationen @Path, @Consumes und @Produces werden übernommen @ApiResponse ein Rückgabewert nebst Fehlercode @Parameter ermöglicht die Daten aus den JAX-RS Parameter Annotationen zu erweitern @Content gibt den content/ media Type für Parameter und Responses an @Schema konkrete Schemainhalte, zusätzlich werden auch JAXB und Bean Validation Annotationen verarbeitet
17. CODE FIRST: HELLO DEMO MIT CXF UND SPRING BOOT alternativ git clone https://github.com/apache/cxf cd distribution/src/main/release/samples/jax_rs/spring_boot mvn spring-boot:run x-www-browser http://localhost:8080/services/helloservice/\ api-docs?url=/services/helloservice/openapi.json Download der CXF Quellcode Distribution
18. CODE FIRST: PETSTORE DEMO MIT CXF UND SPRING BOOT git clone https://github.com/deki/swagger-samples/ --branch java-cxf-spring-boot-m cd java/java-cxf-spring-boot-minimal mvn spring-boot:run x-www-browser http://localhost:8080/services/api-docs?url=/services/openapi.yaml
19. ALTERNATIVEN ZUR OPENAPI SPECIFICATION fokussiert sich stärker auf die menschliche Lesbarkeit und Einfachheit APIs werden in einer Markdown-ähnlichen Syntax beschrieben ist YAML-basiert und erlaubt komplexere Definitionen als Swagger 2.0 Muleso als Ersteller ist inzwischen der Open API Initiative beigetreten API Blueprint RESTful API Modeling Language (RAML)
20. ANWENDUNGSBEISPIELE: ZALANDO einer der umsatzstärksten deutschen Online-Shops schreiben API-First Prinzip und Dokumentation nach OpenAPI Specification vor intern werden eine Vielzahl von APIs zwischen den Services autonomer Teams genutzt öffentliche wartet mit OAS 3 bis Tool-Unterstützung gegeben ist Richtlinien API zum Abruf von u.a. Artikeln und Bewertungen
21. ANWENDUNGSBEISPIELE: LUFTHANSA größtes Lu verkehrsunternehmen Deutschlands stellt seit diesem Jahr mit der eine Schnittstelle zur Verfügung mit der sich bspw. Flugpläne und Flugstatus auslesen lassen entwickelt vom Lu hansa Innovation Hub und kürzlich mit dem Digital Leader Award prämiert bislang keine Angaben zur Umstellung auf OAS 3 Lu hansa Open API
22. ANWENDUNGSBEISPIELE: EBAY weltweit größter Online-Marktplatz bietet an (Sell, Buy, Commerce, Searching APIs) Beta Version einiger APIs unterstützt OAS 3, z.B. zahlreiche APIs Buy Browse API
23. UNTERSCHIEDE ZWISCHEN VERSION 2.0 UND 3.0.X
28. NICHT ENTHALTEN Alternative Schema wie sind in der Diskussion, wurden bislang aber noch nicht in die Specification integriert. Für asynchrone Anwendungsfälle wie MQTT und AMQP wurde daher basierend auf der OpenAPI Specification die ins Leben gerufen. Google Protocol Buffers AsyncAPI Specification
29. FAZIT Swagger 2.0 ist Quasi-Standard hohe Verbreitung bei REST-basierten Anwendungen umfangreiche Tool-Unterstützung OpenAPI Specification 3.0.x sorgt für Ordnung breites Gremium, in dem alle namha en Hersteller vertreten sind wird sich durchsetzen und Swagger 2.0 ablösen, sobald die Tool-Unterstützung angepasst ist
30. BILDQUELLEN , , , , , , , , , , Public Domain Pixabay geralt CC0 Creative Commons Pixabay geralt CC0 Creative Commons Pixabay congerdesign CC0 Creative Commons Pexels rawpixel.com CC0 Creative Commons Pexels startupstockphotos.com CC0 Creative Commons Pixabay Free-Photos CC0 Creative Commons Pexels Markus Spiske CC0 Creative Commons Pixabay MorganK CC0 Creative Commons Zalando Corporate Communications Lu hansa Group Communications Darrel Miller Open API Initiative Darrel Miller Open API Initiative Darrel Miller Open API Initiative Darrel Miller Open API Initiative Pixabay wilhei CC0 Creative Commons Huw Williams