Open Source im professionellen Einsatz

Swagger 2 wird Open API 3

22.03.2017

APIs definieren und dokumentieren klappt mit Swagger bestens. Das Projekt gehört inzwischen zur Linux Foundation und ändert seinen einprägsamen Namen leider von Swagger zu Open API. Immerhin gibt es eine neue Version.

287

Die Änderungen von Open API 3 lassen sich in einem begleitenden Blogpost betrachten. Die architektonischen Unterschiede zwischen den APIs in Version 2 und 3 zeigt eine in den Blogpost integrierte Grafik recht anschaulich. Das neue API sieht strukturell etwas aufgeräumter aus.

Weiterhin sollten die Open-API-Nutzer nun Yaml 1.2 verwenden, zugleich unterstützt Open API 3 mehr Json Schema ("oneOf", "anyOf", "not", "nullable", "deprecated", "writeOnly"). Daneben setzt Open API nun auf Semantic Versioning: Die aktuelle Versionsnummer lautet also 3.0.0. Anstelle des von Git inspirierten Markdown setzen die Open-API-Macher künftig auf Common Mark, einen Versuch, Markdown zu standardisieren.

Architekturänderungen zwischen Swagger 2 und Open API 3 (Quelle: https://stuff.rdme.io).

Ließ Swagger 2 seine Anwender noch einen "host", "basePath" und "schemes" definieren, legen sie in Open API 3 mehrere URLs fest, wobei auch Path Templating erlaubt ist. Components sind definierbare Objekte, die sich an mehreren Stellen einsetzen lassen. Sie ersetzen die weniger gut definierten "definitions" von Swagger 2. Der Blogpost zeigt eine Liste.

Ebenfalls etwas Verwirrung stifteten in Swagger 2 "body" und "formData", eine Untermenge von "parameters". Das erste findet sich nun in einem Bereich namens "requestBody" wieder und wurde mit dem zweiten zusammengeführt. Außerdem bringt "requestBody" eine reihe neuer Features mit, die der blogpost ebenfalls vorstellt.

"Response Format" ist nun komplexer, über das neu eingeführte Linking lassen sich über Links Folge-Informationen besser vernetzen. Nicht zuletzt gibt es Security-Updates. So wurden die Flow-Namen von Oauth2 aktualisiert, und es gibt Support für Open-ID-Verbindungen. Wer sich in die neue Version einarbeiten will, liest am besten den Blogpost und findet ansonsten auf Github Informationen.

Ähnliche Artikel

  • Swagger API

    Ein REST-API nützt einem Entwickler vor allem dann, wenn der API-Anbieter die Methoden ausführlich dokumentiert. Genau dabei hilft das Toolpaket Swagger. Dessen Werkzeuge generieren nicht nur halbautomatisch eine API-Referenz, sondern auch ein passendes Client-SDK für zahlreiche Programmiersprachen.

  • Atlascamp 2016: Mehr Kollaboration, mehr Cloud, mehr Geld

    Im Atlascamp stellte Hersteller Atlassian heute die Neuerungen rund um Jira, Bitbucket, Confluence und Co. vor. Das Unternehmen selbst tritt der Open-API-Initiative bei, veröffentlicht Radar als Open Source und verbessert die Continuous Integration für Bitbucket.

  • Kubernetes 1.4 erleichtert Installation und Betrieb

    Viele Container einfach zu verwalten strebt die von Google entwickelte Software Kubernetes an. Nun erreicht sie Version 1.4, die sich vor allem einfacher installieren und nutzen lassen soll.

  • REST

    Obwohl sie keiner wirklich neuen Idee folgen, erfreuen sich REST-APIs seit einiger Zeit erhöhter Beliebtheit auf Seiten der Industrie, aber auch kleinerer Projekte. Der Artikel erklärt, warum das so ist, und veranschaulicht den recht abstrakten Architekturansatz an einem fasslichen Beispiel.

  • Open SSL will Lizenz ändern

    Open SSL soll künftig in noch mehr FOSS-Produkten zum Einsatz kommen, daher wollen die Entwickler nun die Lizenz ändern. Doch das ist nicht ganz einfach.

comments powered by Disqus

Stellenmarkt

Artikelserien und interessante Workshops aus dem Magazin können Sie hier als Bundle erwerben.