Co je OpenAPI specifikace
OpenAPI specifikace (OpenAPI Specification, OAS) je standardní formát pro popis REST API v jediném strojově čitelném souboru, psaném v jazyce YAML nebo JSON. Vyjmenuje každý endpoint, parametry, které přijímá, data, která vrací, i způsob, jak se požadavky ověřují. Dřív se jmenovala Swagger a u řady souvisejících nástrojů na tento název dodnes narazíte.
Smysl je jeden sdílený zdroj pravdy. Místo ručně psaného dokumentu, který zastará, máte přesnou smlouvu, kterou přečtou lidé i software.
Lidsky řečeno
Představte si to jako technický výkres stavby. Architektův plán řekne každé profesi přesně, kde vedou zdi a trubky, takže instalatér i elektrikář pracují podle stejného nákresu. OpenAPI soubor dělá totéž pro API: každému vývojáři i nástroji řekne, jak přesně API vypadá.
Proč na tom záleží
Protože je soubor strukturovaný, nástroje ho umí přečíst a udělat za vás kus práce:
- Interaktivní dokumentace. Vygenerujete přehled, ve kterém si vývojáři zkoušejí volání rovnou v prohlížeči.
- Generování kódu. Vytvoříte klientské knihovny i kostry serveru téměř v jakémkoli jazyce, takže nikdo nepíše opakující se kód ručně.
- Mock servery. Ze specifikace postavíte falešné API, takže klienti začnou stavět ještě dřív, než vznikne to skutečné.
- Automatické testy. Ověříte, že běžící API opravdu odpovídá tomu, co specifikace slibuje.
Pro váš tým to znamená rychlejší integraci, méně nedorozumění a takovou zkušenost vývojářů, kdy vašemu API rozumí bez doptávání.
Na co si dát pozor
- Specifikace se rozejde se skutečným API. Dokument, který už neodpovídá kódu, je horší než žádný, protože mu lidé věří a spálí se. Ověřujte API proti specifikaci v CI pipeline.
- Berete to jen jako dokumentaci. OpenAPI má největší cenu jako smlouva, kterou navrhnete první a podle které pak stavíte, ne jako soubor psaný dodatečně.
- Přehnaná podrobnost na začátku. Začněte u endpointů a tvarů dat, na kterých záleží. Popisy a příklady doladíte, až se API ustálí.
Související články
- Co je API? - To, co OpenAPI soubor popisuje.
- Zlepšete adopci API s OpenAPI specifikací - Hlubší pohled na přístupy design-first a code-first v praxi.
- Co je GraphQL? - Jiný přístup k API, který popisuje smlouvu po svém.
Chcete být o krok napřed?
Nenechte si utéct naše nejlepší postřehy. Žádný spam, jen praktické analýzy, pozvánky na exkluzivní eventy a shrnutí podcastů přímo do vaší schránky.