OpenAPI/Swagger

Proč dokumentovat API pomocí OpenAPI/Swagger

OpenAPI (dříve Swagger Specification) je de facto standard pro strojově čitelnou specifikaci REST/HTTP API. Jediný zdroj pravdy (specifikační soubor) slouží jako základ pro generování dokumentace, SDK klientů, serverových stubů, validaci požadavků/odpovědí, testování i mockování. Správně navržená OpenAPI specifikace snižuje náklady na integrace, zvyšuje konzistenci a zrychluje 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 využívá nativně JSON Schema. To umožňuje přesné vyjádření typů, omezení a validačních pravidel:

• 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 vlastní vocabulary rozšíření.

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, stylování (form, spaceDelimited, pipeDelimited, deepObject).
• requestBody: multimediální obsah (content) s schema a examples pro různé MIME typy.
• responses: mapování 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 rootu 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 na operaci/parametru/schéma; dokumentujte náhrady.
• Stability labels: experimental, beta, ga (pomocí x-* rozšíření).

Refaktorizace a znovupoužití pomocí $ref

Specifikaci rozdělujte do více souborů a referencujte relativními 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 s $dynamicRef v rámci JSON Schema).

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

Stylistika a konzistence

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

Dokumentační UX: 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ěkné dokumentace s vyhledáváním, fixními odkazy a interaktivním testem.

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 kontrakt-first

• Mock server z OAS pro paralelní vývoj UI a backendu.
• Contract testing (např. při CI): validace, zda implementace odpovídá schématům (request/response validators v gatewayi).
• Generované testy: z examples a schemas lze odvodit smoke testy a negative testy.

Automatizace v CI/CD: linting, bundling a publikace

• Linting: pravidla pro styl, názvosloví, kódy chyb, bezpečnost (např. požadavek na operationId, zákaz „any“ typů).
• 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, verze 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 retry.
• Serverové stuby s předpřipraveným routingem, validací a skeletony handlerů.
• Typing: generované typy s přesnou sémantikou (discriminátory, uniony) pro FE/BE.

Hypermedia a navigace: links a callbacks

• links: popis návazností odpověď → další požadavek (např. z orderId na /orders/{id}).
• callbacks: server iniciuje volání na dříve registrovaný klientský endpoint (např. event 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

• content negotiation: více formátů (application/json, application/xml, text/csv).
• Binary/stream: type: string + format: binary pro download/upload souborů, limitace velikosti přes hlavičky.
• Kompatibilita: pečlivě pracujte s additionalProperties a unevaluatedProperties (JSON Schema) pro forward kompatibilitu.

Dokumentace pro interní vs. externí uživatele

• Interní: detailní chování, interní kódy chyb, operativní poznámky, runbooky a rate-limits.
• 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).

Design pro výkon, škálování a spolehlivost

• Idempotentní operace s Idempotency-Key pro POSTy, bezpečné retry.
• Stránkování (cursor/offset), filtr/sort; popsat limity a determinismus výsledků.
• Rate limiting a hlavičky (Retry-After, X-RateLimit-*); doporučit backoff strategie.

Mezinárodní prostředí a lokalizace

• i18n: popis časových zón, formátů dat (date-time v UTC), číselných formátů, 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 linky).
• Nekonzistentní kódy chyb, směšování doménových a technických chyb.
• Přetížení query parametrů namísto správného modelu v requestBody.
• Nedostatečné examples, chybějící okrajové případy a ukázky chyb.
• Používání free-form objektů bez omezení, které láme kompatibilitu.

Šablona redakčního workflow dokumentace

1. Návrh rozhraní (kontrakt-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í, compliance.
4. Publikace – portál, verze, changelog, migrační průvodce.
5. Údržba – deprecations, roadmapa, zpětná vazba od vývojářů.

Changelog a migrační průvodce

• Changelog v info nebo samostatně: přehledně popsat breaking/behavioral změny.
• 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 „manual“ – 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 CI/CD automatizace (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ším čase integrace, menší chybovosti a spokojenějších vývojářích.