Swagger je open source framework pro návrh, tvorbu, dokumentaci a konzumaci RESTful web API. Kromě editoru pro tvorbu nového web API rozhraní, obsahuje Swagger i nástroje pro automatizovanou dokumentaci a testování existujícího API (dle URL API), nástroj pro generování kódu podle zadaného rozhraní a taky nástroj pro vizualizaci a vyzkoušení navrženého API ještě před jeho implementací.

Swagger je podporován společností SmartBear Software, která se aktivně zapojila i do vzniku OpenAPI Initiative. Během vzniku OpenInitiative byla původní specifikace Swagger 2.0 předána do OpenAPI Initiative a tím vznikla specifikace OpenAPI 2.0. Tím došlo k oddělení Swaggeru od specifikace a dál už platí, že OpenAPI je specifikace a Swagger jsou nástroje pro implementaci této specifikace.

Historie

Vznik Projekt Swagger API začal vytvářet v roce 2009 Tony Tam, technický spoluzakladatel anglického slovníku Wordnik ve firmě Reverb Technologies. V průběhu vývoje Wordniku byl Tam frustrován často opakovanou dokumentací API rozhraní a opakovaným generováním klientského SDK – oboje volalo po automatizaci. Tam proto navrhl jednoduché zobrazení API ve formátu JSON, které by stavělo na flexibilitě REST architektury a které by umožňovalo další funkce, jaké se používaly v nástrojích pro SOAP protokol. Koncept interaktivního uživatelského rozhraní připravil Ayush Gupta, Ramesh Pidikiti vedl implementaci původního generátoru kódu a návrhář / vývojář Zeke Sikilianos vytvořil jméno Swagger.

V srpnu 2011 byla vydána první specifikace Swaggeru – verze 1.0 Následovaly drobné úpravy ve verzi 1.1 (srpen 2012) a v březnu 2014 byla vydána verze 1.2 – první formální specifikace Swaggeru, ve které došlo k oddělení specifikace od implementace.

Swagger 2.0 a SmartBear V září 2014 byla vydána verze 2.0 ve které došlo k reorganizaci původního formátu swaggeru – místo dvou souborů je potřeba už jen jeden soubor – a také k dalším změnám jako byla širší podpora JSON schéma, podpora API metadat a další.

V březnu 2015 převzal podporu nad Swaggerem SmartBear Software, kam přestoupil v září 2015 i Tony Tam jako viceprezident.

OpenAPI 2.0 V prosinci 2015 darovala SmartBear Software specifikaci swaggeru 2.0 do nově vzniklé OpenAPI iniciativy. Tím vznikla tzv. OpenAPI specifikace v 2.0 (obsahově shodná s původní specifikací Swagger 2.0) a byla přesunuta do nového úložiště v GitHubu. Od tohoto okamžiku je možné chápat OpenAPI jako specifikaci a Swagger jako nástroj pro implementaci této specifikace.

OpenAPI 3.0 V červenci 2017 byla vydána OpenAPI specifikace verze 3.0, ve které došlo k některým změnám, jako např.:

zjednodušení struktury a snazší znovu-použitelnost některých komponent rozšíření práce s tělem zpráv (body v requestu a v responsi) vylepšení definic pro zabezpečení včetně sjednocení OAuth 2 s terminologií, která se používá v OAuth 2 vylepšení datových typů, které lze použít jako parametr a další

Přehled nástrojů Swaggeru

Návrh a vývoj API Swagger Editor umožňuje manuální tvorbu rozhraní

Swagger Inspector slouží pro automatické generování dokumentace na základě existujících API.

Swagger Codegen slouží ke generování zdrojového kódu pro server a pro klienta z daného popisu rozhraní.

Interakce s API Swagger UI a Swagger Inspector umožňují provolat a testovat vlastní API (Swagger UI) nebo libovolné existující API (Swagger Inspector).

Dokumentace API Swagger Editor a Swagger UI umožňují interaktivně tvořit a popisovat rozhraní. Zároveň si lze takto popsaná rozhraní přímo vyzkoušet, včetně error volání.

Srovnání s konkurencí Kromě Swagger / OpenAPI specifikace, existují i další formáty pro popis API rozhraní, jako jsou RAML, API Blueprint (apiary.io) a další (WADL, Slate…).

Výhody a nevýhody Jako hlavní výhody a nevýhody se uvádí:

Swagger / OpenAPI Výhody: Velmi rozšířený, velká komunita uživatelů a podporovatelů, největší podpora programovacích jazyků, velmi dobrá dokumentace a návody

Nevýhody: Postrádá možnost rozšířených konstrukcí pro metadata, vyžaduje použití schémat pro všechny typy odpovědí, není jednoduché s ním začít

RAML Výhody: Podporuje rozšířené konstrukce, dostatečně rozšířený, lidsky čitelný formát, je snadné s ním začít

Nevýhody: Postrádá dostatečnou dokumentaci a návody nad rámec specifikace, omezené znovu-použití kódu, slabá podpora pro nové verze specifikací

API Blueprint Výhody: Snadno pochopitelný, jednoduchý pro zápis rozhraní

Nevýhody: Málo rozšířený, postrádá rozšířené konstrukce, složitý na instalaci

Související články REST – Representational State Transfer Přehled jazyků pro popis RESTful API, jako jsou RAML, WADL a WSDL

Reference

Externí odkazy

Stránky Open API Initiative (OAI) Web Swagger Specifikace OpenAPI na GitHubu Eclipse OpenAPI (OAS) Editor a Studio Swagger – nástroj pro dokumentaci API

Kategorie:Software Kategorie:Open-source