Cesko.wiki Swagger (software)
Author
Albert FloresSwagger 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. +more0 předána do OpenAPI Initiative a tím vznikla specifikace OpenAPI 2. 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. +more 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. +more1 (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. +more 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 [url=https://github. com/OAI/OpenAPI-Specification]GitHubu[/url]. 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
Statistiky použití
Pro srovnání, jak moc se používá který nástroj, viz např.:
* [url=https://stackshare. io/stackups/api-blueprint-vs-raml-vs-swagger-ui]stackshare. +moreio[/url] - v listopadu 2019 zde Swagger převyšoval ostatní nástroje cca desetinásobně * [url=https://trends. google. com/trends/explore. date=today%205-y&q=swagger%20api,raml%20api,api%20blueprint,openapi]Google Trends[/url]- v listopadu 2019 zde hledání swagger api / open api převyšuje hledání ostatních nástrojů více než dvacetinásobně * [url=https://www. npmjs. com/package/swagger-tools]npm: swagger-tools[/url], [url=https://www. npmjs. com/package/raml]npm: raml[/url], [url=https://www. npmjs. com/package/apiaryio]npm: apiaryio[/url] - sice nejde o zcela srovnatelné nástroje, ale pro představu - swagger-tools dosahuje v listopadu 2019 desítky tisíc stažení týdně, zatímco ostatní nástroje se stahují méně než stokrát - tzn. až tisícinásobný rozdíl.
Související články
REST - Representational State Transfer * Přehled jazyků pro popis RESTful API, jako jsou RAML, WADL a WSDL
Reference
Externí odkazy
[url=https://openapis. org/]Stránky Open API Initiative (OAI)[/url] * [url=http://swagger. +moreio]Web Swagger[/url] * [url=https://github. com/OAI/OpenAPI-Specification]Specifikace OpenAPI na GitHubu[/url] * [url=https://marketplace. eclipse. org/content/openapi-studio-rich-oas3-editor]Eclipse OpenAPI (OAS) Editor a Studio[/url] * [url=http://promptsoftech. com/blog/how-to-use-swagger-tool-for-api-documentation/]Swagger - nástroj pro dokumentaci API[/url].