Wikipedie

Swagger (software)

open source framework

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
Logo
VývojářSmartBear software
První vydání2011
Typ softwaruAPI editor, validator, inspector, code generator
LicenceApache License, Version 2.0
Webhttps://swagger.io/
Některá data mohou pocházet z datové položky.

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

Vznik editovat

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

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

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

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

Návrh a vývoj API editovat

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

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

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

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

Jako hlavní výhody a nevýhody se uvádí:[12][13][14]

Swagger / OpenAPI editovat

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

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

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

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

Reference editovat

V tomto článku byl použit překlad textu z článku Swagger (software) na anglické Wikipedii.

  1. ↑ a b c Swagger editor [online]. swagger.io [cit. 2019-11-23]. Dostupné online. 
  2. ↑ a b Swagger inspector [online]. swagger.io [cit. 2019-11-23]. Dostupné online. 
  3. ↑ a b c Swagger Codegen [online]. swagger.io [cit. 2019-11-23]. Dostupné online. 
  4. ↑ a b c Swagger UI [online]. swagger.io [cit. 2019-11-23]. Dostupné online. 
  5. ↑ a b OpenAPI Specification - Revision History [online]. OpenAPI Initiative [cit. 2019-11-23]. Dostupné online. 
  6. ↑ 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. 
  7. ↑ PINKHAM, Ryan. What Is the Difference Between Swagger and OpenAPI? [online]. [cit. 2019-11-23]. Dostupné online. 
  8. ↑ AMUNDSEN, Mike. APIs with Swagger : An Interview with Reverb’s Tony Tam [online]. [cit. 2019-11-23]. Dostupné online. 
  9. ↑ a b c OpenAPI Specification v2 [online]. swagger.io [cit. 2019-11-23]. Dostupné online. 
  10. ↑ PINKHAM, Ryan. A Guide to What’s New in OpenAPI 3.0 [online]. [cit. 2019-11-23]. Dostupné online. 
  11. ↑ Documenting Your Existing APIs: API Documentation Made Easy with OpenAPI & Swagger [online]. swagger.io [cit. 2019-11-23]. Dostupné online. 
  12. ↑ SANDOVAL, KRISTOPHER. Top Specification Formats for REST APIs [online]. 2016-03-19 [cit. 2019-11-23]. Dostupné online. 
  13. ↑ Swagger (OAS) vs. RAML - Which is Better for Building APIs? [online]. [cit. 2019-11-23]. Dostupné online. 
  14. ↑ Stackshare - API Blueprint vs RAML vs Swagger UI [online]. [cit. 2019-11-23]. Dostupné online. 

Externí odkazy editovat

Citováno z „https://cs.wikipedia.org/w/index.php?title=Swagger_(software)&oldid=23679580“