Dokumentace API pomocí OpenAPI/Swagger: standardizace

API a REST služby
P. Varga
Dokumentace API pomocí OpenAPI/Swagger: Standardizace

Proč dokumentovat API pomocí OpenAPI/Swagger

OpenAPI (dříve Swagger Specification) je faktickým standardem pro strojově čitelnou specifikaci REST/HTTP API. Jediný zdroj pravdy (soubor se specifikací) slouží jako základ pro generování dokumentace, SDK klientů, serverových stubů, validaci požadavků a odpovědí, testování i mockování. Správně navržená specifikace OpenAPI snižuje náklady na integrace, zvyšuje konzistenci a urychluje onboarding vývojářů i partnerů.

Terminologie: OpenAPI vs. Swagger

  • OpenAPI Specification (OAS): formát specifikace (verze 3.0/3.1), otevřený standard pod Linux Foundation.
  • Swagger: původní název specifikace a sada nástrojů (Swagger UI, Swagger Editor, Swagger Codegen).
  • OAS 3.1 vs. 3.0: OAS 3.1 je plně kompatibilní s JSON Schema (2020-12), podporuje webhooks, vylepšené nullable/default a přesnější sémantiku pro oneOf/anyOf/allOf.

Struktura specifikace OAS 3.x

  • openapi: verze specifikace (např. 3.1.0).
  • info: metadata API (název, verze, kontakt, licence).
  • servers: základní URL a proměnné prostředí.
  • paths: jednotlivé koncové body a operace (GET/POST/… ).
  • components: znovupoužitelné části (schemas, responses, parameters, requestBodies, headers, securitySchemes).
  • security: globální požadavky na autorizaci.
  • tags a externalDocs: organizace a odkazy.
  • webhooks (OAS 3.1): zpětná volání iniciovaná serverem.

Minimální příklad v YAML

openapi: 3.1.0 info: title: Fakturační API version: 1.2.0 servers: - url: https://api.example.com/v1 paths: /invoices: get: summary: Seznam faktur tags: [Invoices] parameters: - in: query name: page schema: { type: integer, minimum: 1, default: 1 } responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/InvoicePage" components: schemas: Money: type: object properties: currency: { type: string, pattern: "^[A-Z]{3}$" } amount: { type: number, multipleOf: 0.01 } required: [currency, amount] Invoice: type: object properties: id: { type: string, format: uuid } total: { $ref: "#/components/schemas/Money" } status: { enum: [DRAFT, SENT, PAID, VOID] } required: [id, total, status] InvoicePage: type: object properties: items: { type: array, items: { $ref: "#/components/schemas/Invoice" } } nextPage: { type: integer, nullable: true }

Modelování dat pomocí JSON Schema

OAS 3.1 nativně využívá JSON Schema. To umožňuje přesně vyjádřit typy, omezení a validační pravidla:

  • Kombinátory: oneOf, anyOf, allOf, not.
  • Discriminátor pro polymorfismus s explicitním směrováním na konkrétní schémata.
  • Formáty (email, uuid, date-time) a rozšíření pomocí vlastních vocabulary.
Vehicle: oneOf: - $ref: "#/components/schemas/Car" - $ref: "#/components/schemas/Truck" discriminator: propertyName: type Car: type: object properties: { type: { const: "car" }, doors: { type: integer, minimum: 2 } } required: [type, doors]

Parametry, těla požadavků a obsah

  • parameters: in: path|query|header|cookie, styl serializace (form, spaceDelimited, pipeDelimited, deepObject).
  • requestBody: multimediální obsah (content) se schema a examples pro různé MIME typy.
  • responses: mapování stavových kódů (včetně default), headers a links (HATEOAS).
/invoices/{id}: get: parameters: - in: path name: id required: true schema: { type: string, format: uuid } responses: "200": description: Detail faktury content: application/json: schema: { $ref: "#/components/schemas/Invoice" } "404": $ref: "#/components/responses/NotFound" components: responses: NotFound: description: Nenalezeno content: application/problem+json: schema: type: object properties: type: { type: string, format: uri } title: { type: string } status: { type: integer, const: 404 } detail: { type: string }

Bezpečnost a autorizace

  • securitySchemes: OAuth2 (authorizationCode, clientCredentials, deviceCode), mTLS, API klíče v hlavičce/parametru/cookie, HTTP Basic/Bearer.
  • scopes: jemnozrnná oprávnění pro operace/domény.
  • Globální vs. lokální definice požadavků (sekce security na kořenové úrovni vs. u operací).
components: securitySchemes: oauth: type: oauth2 flows: authorizationCode: authorizationUrl: https://idp.example.com/auth tokenUrl: https://idp.example.com/token scopes: invoices.read: Čtení faktur invoices.write: Zápis faktur security: - oauth: [invoices.read]

Verzování a životní cyklus API

  • Semantic Versioning v info.version a/nebo v servers.url (/v1 vs. /v2).
  • Deprecation: pole deprecated: true u operace/parametru/schématu; dokumentujte náhrady.
  • Stability labels: experimental, beta, ga (pomocí rozšíření x-*).

Refaktorizace a opětovné použití pomocí $ref

Rozdělujte specifikaci do více souborů a odkazujte na ně pomocí relativních URI. Používejte $ref napříč components a paths. Pamatujte, že v místě $ref nesmí být sourozenecké klíče (s výjimkou OAS 3.1, kde lze v rámci JSON Schema použít $dynamicRef).

components: schemas: Address: $ref: "./schemas/common.yaml#/Address"

Styl a konzistence

  • REST konvence: podstatná jména označující zdroje v množném čísle (/invoices), hierarchie (/customers/{id}/invoices).
  • Sémantika HTTP: idempotence (GET/PUT/DELETE), bezpečnost (GET bez vedlejších účinků), použití PATCH s JSON Patch/Merge Patch.
  • Chybové odpovědi: konzistentní formát (např. application/problem+json), kódy 4xx/5xx a korelační ID.

Uživatelská zkušenost s dokumentací: příklady, popisy a „try it out“

  • summary a description pište výstižně; uvádějte obchodní kontext a hraniční případy.
  • examples na úrovni content i schema; uveďte happy path i chyby.
  • Swagger UI / Redoc: generování přehledné dokumentace s vyhledáváním, trvalými odkazy a interaktivním testováním.
content: application/json: schema: { $ref: "#/components/schemas/Invoice" } examples: sample: summary: Jednoduchá faktura value: { id: "0c8c…", status: "PAID", total: { currency: "CZK", amount: 1520.00 } }

Mockování, testování a přístup contract-first

  • Mock server vytvořený z OAS pro paralelní vývoj uživatelského rozhraní a backendu.
  • Contract testing (např. v CI): validace, zda implementace odpovídá schématům (validátory request/response v API gatewayi).
  • Generované testy: z examples a schemas lze odvodit smoke testy a negativní testy.

Automatizace v CI/CD: linting, bundling a publikace

  • Linting: pravidla pro styl, názvosloví, chybové kódy a bezpečnost (např. požadavek na operationId, zákaz typů „any“).
  • Bundling: sloučení více souborů do jednoho artefaktu pro publikaci (developer portal, gateway).
  • Validace: syntaktická i sémantická (např. konfliktní cesty, chybějící odpovědi).
  • Publikace: automatické nasazení do portálu, verzování dokumentace podle tagů vydání.

Generování kódu: klienti, servery a typy

  • SDK (TypeScript/Java/C#/Python/Go…): s typovou bezpečností, interceptory pro autorizaci a opakované pokusy.
  • Serverové stuby s připraveným routováním, validací a kostrami obslužných metod.
  • Typování: generované typy s přesnou sémantikou (discriminátory, sjednocené typy) pro FE/BE.

Hypermedia a navigace: links a callbacks

  • links: popis návaznosti odpověď → další požadavek (např. z orderId na /orders/{id}).
  • callbacks: server zahájí volání na dříve zaregistrovaný klientský endpoint (např. událost o dokončení platby).
responses: "201": description: Vytvořeno links: GetInvoice: operationId: GetInvoice parameters: id: "$response.body#/id"

Vícemediální obsah a verze schémat

  • Vyjednávání obsahu: více formátů (application/json, application/xml, text/csv).
  • Binární data/proud: type: string + format: binary pro stahování/nahrávání souborů, omezení velikosti pomocí hlaviček.
  • Kompatibilita: pečlivě pracujte s additionalProperties a unevaluatedProperties (JSON Schema) kvůli zpětné kompatibilitě.

Dokumentace pro interní a externí uživatele

  • Interní: podrobné chování, interní chybové kódy, provozní poznámky, runbooky a limity počtu požadavků.
  • Externí: jasné scénáře, rychlý start (API key/OAuth flow), vzorové požadavky, sandbox.
  • Verzované portály: možnost přepínat dokumentaci mezi verzemi a prostředími (prod/stage/sandbox).

Návrh s ohledem na výkon, škálovatelnost a spolehlivost

  • Idempotentní operace s Idempotency-Key pro požadavky POST a bezpečné opakování požadavků.
  • Stránkování (cursor/offset), filtrování/třídění; popište limity a deterministické řazení výsledků.
  • Omezení počtu požadavků a hlavičky (Retry-After, X-RateLimit-*); doporučte strategie exponenciálního čekání.

Mezinárodní prostředí a lokalizace

  • i18n: popis časových pásem, formátů dat (date-time v UTC), číselných formátů a měn.
  • Jazyky dokumentace: přepínání jazyků portálu; překlady description a příkladů.

Nejčastější chyby v OpenAPI a jak se jim vyhnout

  • Chybějící operationId (komplikuje generování SDK a odkazů).
  • Nekonzistentní chybové kódy, směšování doménových a technických chyb.
  • Nadměrné využívání query parametrů namísto správného modelování pomocí requestBody.
  • Nedostatečné examples, chybějící okrajové případy a ukázky chyb.
  • Používání volně definovaných objektů bez omezení, které narušuje kompatibilitu.

Šablona redakčního workflow dokumentace

  1. Návrh rozhraní (contract-first) – definice zdrojů, operací, schémat a chyb.
  2. Revize – technická (architekti), produktová (PM), bezpečnostní (IAM/infosec).
  3. Lint a validace – automatické kontroly stylu, názvosloví a souladu s požadavky.
  4. Publikace – portál, verze, changelog, migrační průvodce.
  5. Údržba – ukončování podpory, plán dalšího vývoje, zpětná vazba od vývojářů.

Changelog a migrační průvodce

  • Changelog v info nebo samostatně: přehledně popište změny, které narušují kompatibilitu, i změny chování.
  • Migration guides: mapování starých cest/parametrů na nové, vzorové transformace požadavků/odpovědí.

Závěr: OpenAPI jako páteř vývojářského ekosystému

Dokumentace API pomocí OpenAPI/Swagger není jen „manuál“ – je to smlouva mezi týmy a nástroj pro automatizaci. Kombinace dobrého návrhu, konzistentních schémat, kvalitních příkladů a automatizace CI/CD (linting, validace, publikace) vede k robustním, bezpečným a snadno integrovatelným API. Investice do specifikace se mnohonásobně vrátí v kratší době integrace, menším počtu chyb a spokojenějších vývojářích.