OpenAPI/Swagger jako standard pro dokumentaci API

Proč dokumentovat API pomocí OpenAPI/Swagger

OpenAPI (dříve Swagger Specification) je de facto standardem 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ů a odpovědí, testování i mockování. Správně navržená OpenAPI specifikace 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 webhooky, 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ření datových 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í rozšíření 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, různé styly serializace (form, spaceDelimited, pipeDelimited, deepObject).
• requestBody: multimediální obsah (content) s 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 bezpečnostních požadavků (sekce security na rootu vs. u jednotlivých 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 operací, parametrů nebo schémat; dokumentujte náhrady.
• Stavové štítky: experimental, beta, ga pomocí x-* rozšíření.

Refaktorizace a znovupoužití pomocí $ref

Specifikaci rozdělte do více souborů a referencujte relativními URI. Používejte $ref v rámci components i paths. Uvědomte si, že v místě $ref nesmí být sourozenecké klíče (s výjimkou OAS 3.1 při použití $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), hierarchická struktura (/customers/{id}/invoices).
• HTTP sémantika: idempotentní metody (GET/PUT/DELETE), bezpečné GET (bez vedlejších efektů), použití PATCH s JSON Patch/Merge Patch.
• Chybové odpovědi: konzistentní formát (např. application/problem+json), relevantní 4xx/5xx kódy a korelační 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 okrajové případy.
• examples na úrovni content i schema; zahrňte happy path i chybové scénáře.
• Swagger UI / Redoc: generuje přehlednou dokumentaci 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 kontrakt-first přístup

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

Automatizace v CI/CD: linting, bundling a publikace

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

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

• SDK (TypeScript/Java/C#/Python/Go…): s typovou bezpečností, interceptory pro autorizaci a retry mechanizmy.
• Serverové stuby s předpřipraveným routováním, validací a skeletony handlerů.
• Typování: generované typy s přesnou sémantikou (discriminátory, unie) pro frontend i backend.

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 předem registrovaný klientský endpoint (např. event 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: podpora různých formátů (application/json, application/xml, text/csv).
• Binary/stream: type: string s format: binary pro stahování/nahrávání souborů, omezení velikosti přes hlavičky.
• Kompatibilita: pečlivé používání additionalProperties a unevaluatedProperties (JSON Schema) pro forward kompatibilitu.

Dokumentace pro interní vs. externí uživatele

• Interní: detailní popis chování, interní chybové kódy, operativní poznámky, runbooky a limity rychlosti.
• Externí: jasné scénáře použití, rychlý start (API klíče/OAuth flow), vzorové požadavky a sandbox prostředí.
• Verzované portály: možnost přepínat dokumentaci podle verzí a prostředí (produkce/stage/sandbox).

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

• Idempotentní operace s Idempotency-Key pro POST metody, bezpečné opakování požadavků.
• Stránkování (cursor/offset), filtrování a třídění; popsat limity a deterministické výsledky.
• Rate limiting a hlavičky (Retry-After, X-RateLimit-*); doporučit strategie backoff.

Mezinárodní prostředí a lokalizace

• i18n: popis časových zón, formátů dat (date-time v UTC), číselných formátů a měn.
• Jazyky dokumentace: možnost 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 (znesnadňuje generování SDK a vazby mezi operacemi).
• Nekonzistentní kódy chyb, směšování doménových a technických chyb.
• Přetížení query parametrů místo využití strukturovaného requestBody.
• Nedostatečné examples, chybějící okrajové případy a ukázky chybových odpovědí.
• Používání free-form objektů bez omezení, které poškozuje kompatibilitu API.

Šablona redakčního workflow dokumentace

1. Návrh rozhraní (kontrakt-first) – definice zdrojů, operací, schémat a chyb.
2. Revize – technická (architekti), produktová (produktový manažer), bezpečnostní (IAM/infosec).
3. Lint a validace – automatické kontroly stylu, názvosloví, soul