Architekturänderungen zwischen Swagger 2 und Open API 3 (Quelle: https://stuff.rdme.io).
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.
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.
