In der Zeit von Microservice-Architektur und Software-as-a-Service sind APIs aus der Softwareentwicklung nicht mehr wegzudenken. Die unterschiedlichsten Anwendungen oder Services kommunizieren miteinander, h\u00e4ufig auch \u00fcber die Unternehmensgrenze hinaus. In dieser komplexen Welt gibt es nat\u00fcrlich verschiedene Technologien und Begriffe, die auch manchmal miteinander verwechselt werden. Die meisten, die sich mit APIs auseinandergesetzt haben, werden wahrscheinlich auch schon mal die Begriffe Swagger oder OpenAPI geh\u00f6rt haben. Dieser Blog-Artikel soll euch OpenAPI n\u00e4herbringen und euch zeigen, dass die einheitliche Dokumentation von APIs nur ein kleiner Bruchteil der Vorteile ist.<\/p>\n\n\n\n
Beginnen wir mit der Historie von OpenAPI <\/strong>f\u00fcr den Fall, dass man mal bei „Wer wird Million\u00e4r“ sitzt. Die OpenAPI Spezifikation (kurz OAS) ist ein programmiersprachenunabh\u00e4ngiger Standard zur Beschreibung von HTTP-Programmierschnittstellen, wie REST-APIs. Die Geschichte von OpenAPI begann urspr\u00fcnglich unter dem Namen Swagger, welches 2010 von Tony Tam entwickelt und schnell popul\u00e4r wurde, da es Entwicklungsteams erm\u00f6glichte, ihre APIs in einem standardisierten Format zu beschreiben und zu dokumentieren. Im Jahr 2015 wurde das Projekt an die OpenAPI Initiative (OAI) \u00fcbergeben, die von der Linux Foundation gegr\u00fcndet wurde. Das Ziel der OAI war es, die Entwicklung und Verbreitung der Spezifikation weiter voranzutreiben – mit Erfolg, denn OpenAPI ist heute der De-facto-Standard f\u00fcr die Beschreibung von RESTful-APIs. Aber was ist OpenAPI jetzt eigentlich genau?<\/p>\n<\/div><\/div>\n\n\n\n OpenAPI ist letztlich eine Spezifikation, welche mit einer vorgegebenen Syntax, die M\u00f6glichkeit schafft, REST-API-Interfaces einheitlich zu beschreiben. Dazu muss eine OpenAPI Definition erstellt werden, welche in einer YAML- oder JSON-Datei gespeichert wird. In dieser Definition wird der Service und dessen Funktionalit\u00e4t beschrieben, sodass sowohl Menschen als auch Maschinen die Spezifikation des Services lesen k\u00f6nnen.<\/p>\n\n\n\n Damit das ein wenig greifbarer wird, stellen wir uns vor, dass wir einen REST Webservice entwickelt haben, bei dem Entwicklungsteams jeden Morgen den Witz des Tages abrufen k\u00f6nnen. Der Service ist unter der URL https:\/\/api.fabiens-flachwitze.de\/v1 erreichbar. Die einzige Funktion des Service ist die HTTP-Method GET auf den Endpunkt \/joke-of-the-day mit dem man den tagesaktuellen Flachwitz aufrufen kann. Damit andere Entwicklungsteams nun die Witze in ihrer App, zum Beispiel in einer d.velop cloud App auf dem Dashboard anzeigen k\u00f6nnen, sollten wir nun den Webservice beschreiben. Dies machen wir in einer OpenAPI Definition als YAML-File. Das k\u00f6nnte zum Beispiel so aussehen:<\/p>\n\n\n\tBeschreibung des REST Webservice f\u00fcr den Witz des Tages<\/h3>\n\n\n\n