Swagger (software)
 | |
| Vývojář | SmartBear software |
|---|---|
| První vydání | 2011 |
| Typ softwaru | API editor, validator, inspector, code generator |
| Licence | Apache License, Version 2.0 |
| Web | https://swagger.io/ |
| Některá data mohou pocházet z datové položky. | |
Swagger je open source framework pro návrh, tvorbu, dokumentaci a konzumaci RESTful web API. Kromě editoru pro tvorbu nového web API rozhraní,[1] obsahuje swagger i nástroje pro automatizovanou dokumentaci a testování existujícího API (dle URL API),[2] nástroj pro generování kódu podle zadaného rozhraní[3] a taky nástroj pro vizualizaci a vyzkoušení navrženého API ještě před jeho implementací.[4]
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.[5][6] 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.[7]
Historie
[editovat | editovat zdroj]Vznik
[editovat | editovat zdroj]Projekt Swagger API začal vytvářet v roce 2009 Tony Tam, technický spoluzakladatel anglického slovníku Wordnik ve firmě Reverb Technologies.[6][8] 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[9] 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.[9][6]
Swagger 2.0 a SmartBear
[editovat | editovat zdroj]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ší.[9][6]
V březnu 2015 převzal podporu nad Swaggerem SmartBear Software, kam přestoupil v září 2015 i Tony Tam jako viceprezident.[6]
OpenAPI 2.0
[editovat | editovat zdroj]V prosinci 2015 darovala SmartBear Software specifikaci swaggeru 2.0 do nově vzniklé OpenAPI iniciativy.[6][5] 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
[editovat | editovat zdroj]V červenci 2017 byla vydána OpenAPI specifikace verze 3.0, ve které došlo k některým změnám, jako např.:[10]
- 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
[editovat | editovat zdroj]Návrh a vývoj API
[editovat | editovat zdroj]Swagger Editor umožňuje manuální tvorbu rozhraní[1]
Swagger Inspector slouží pro automatické generování dokumentace na základě existujících API.[3][11]
Swagger Codegen slouží ke generování zdrojového kódu pro server a pro klienta z daného popisu rozhraní.[3]
Interakce s API
[editovat | editovat zdroj]Swagger UI a Swagger Inspector umožňují provolat a testovat vlastní API (Swagger UI)[4] nebo libovolné existující API (Swagger Inspector).[2]
Dokumentace API
[editovat | editovat zdroj]Swagger Editor a Swagger UI umožňují interaktivně tvořit a popisovat rozhraní.[1][4] Zároveň si lze takto popsaná rozhraní přímo vyzkoušet, včetně error volání.
Srovnání s konkurencí
[editovat | editovat zdroj]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
[editovat | editovat zdroj]Jako hlavní výhody a nevýhody se uvádí:[12][13][14]
Swagger / OpenAPI
[editovat | editovat zdroj]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
[editovat | editovat zdroj]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
[editovat | editovat zdroj]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í
[editovat | editovat zdroj]Pro srovnání, jak moc se používá který nástroj, viz např.:
- stackshare.io – v listopadu 2019 zde Swagger převyšoval ostatní nástroje cca desetinásobně
- Google Trends[nedostupný zdroj]- v listopadu 2019 zde hledání swagger api / open api převyšuje hledání ostatních nástrojů více než dvacetinásobně
- npm: swagger-tools, npm: raml, npm: apiaryio – 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
[editovat | editovat zdroj]- REST – Representational State Transfer
- Přehled jazyků pro popis RESTful API, jako jsou RAML, WADL a WSDL
Reference
[editovat | editovat zdroj]V tomto článku byl použit překlad textu z článku Swagger (software) na anglické Wikipedii.
- ↑ a b c Swagger editor [online]. swagger.io [cit. 2019-11-23]. Dostupné online.
- ↑ a b Swagger inspector [online]. swagger.io [cit. 2019-11-23]. Dostupné online.
- ↑ a b c Swagger Codegen [online]. swagger.io [cit. 2019-11-23]. Dostupné online.
- ↑ a b c Swagger UI [online]. swagger.io [cit. 2019-11-23]. Dostupné online.
- ↑ a b OpenAPI Specification - Revision History [online]. OpenAPI Initiative [cit. 2019-11-23]. Dostupné online.
- ↑ a b c d e f RALPHSON, Mike. A brief history of the OpenAPI Specification [online]. 2018-12-17 [cit. 2019-11-23]. Dostupné online.
- ↑ PINKHAM, Ryan. What Is the Difference Between Swagger and OpenAPI? [online]. [cit. 2019-11-23]. Dostupné online.
- ↑ AMUNDSEN, Mike. APIs with Swagger : An Interview with Reverb’s Tony Tam [online]. [cit. 2019-11-23]. Dostupné online.
- ↑ a b c OpenAPI Specification v2 [online]. swagger.io [cit. 2019-11-23]. Dostupné online.
- ↑ PINKHAM, Ryan. A Guide to What’s New in OpenAPI 3.0 [online]. [cit. 2019-11-23]. Dostupné online.
- ↑ Documenting Your Existing APIs: API Documentation Made Easy with OpenAPI & Swagger [online]. swagger.io [cit. 2019-11-23]. Dostupné online.
- ↑ SANDOVAL, KRISTOPHER. Top Specification Formats for REST APIs [online]. 2016-03-19 [cit. 2019-11-23]. Dostupné online.
- ↑ Swagger (OAS) vs. RAML - Which is Better for Building APIs? [online]. [cit. 2019-11-23]. Dostupné online.
- ↑ Stackshare - API Blueprint vs RAML vs Swagger UI [online]. [cit. 2019-11-23]. Dostupné online.
Externí odkazy
[editovat | editovat zdroj]
Obrázky, zvuky či videa k tématu Swagger na Wikimedia Commons
