Dokumentace API standardem OpenAPI/Swagger

Proč dokumentovat API pomocí OpenAPI/Swagger

OpenAPI (dříve Swagger Specification) je de facto standardem pro strojově čitelnou specifikaci REST/HTTP API. Jeden 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á 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 webhooky, vylepšené nullable/default a přesnější sémantiku pro oneOf/anyOf/allOf.

Struktura specifikace OAS 3.x

• openapi: verze specifikace (například 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) se 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 úrovni 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: atribut 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ělte do více souborů a referencujte pomocí relativních URI. Používejte $ref napříč components i paths. Pamatujte, že v místě použití $ref nesmí být souběžné 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: názvy zdrojů 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 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 hraniční případy.
• examples na úrovni content i schema; zahrňte happy path i chybové scénáře.
• Swagger UI / Redoc: generování přehledné dokumentace s vyhledáváním, pevný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

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

Automatizace v CI/CD: linting, bundling a publikace

• Linting: pravidla pro styl, názvosloví, chybové kódy, bezpečnost (např. povinnost operationId, zákaz typů „any“).
• Bundling: sloučení více souborů do jednoho artefaktu pro publikaci (developer portal, API 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 logiku.
• Serverové stuby s předpřipraveným směrováním, validací a skeletony handlerů.
• Typing: 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říklad z orderId na /orders/{id}).
• callbacks: server iniciuje volání na předem registrovaný klientský endpoint (například událost 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 více formátů (application/json, application/xml, text/csv).
• Binary/stream: type: string + format: binary pro stahování/nahrávání souborů, limitace velikosti přes hlavičky.
• Kompatibilita: pečlivě pracujte s additionalProperties a unevaluatedProperties (JSON Schema) pro zajištění forward kompatibility.

Dokumentace pro interní vs. externí uživatele

• Interní: detailní chování, interní chybové kódy, operativní poznámky, runbooky a limity rychlosti (rate-limits).
• Externí: jasné scénáře, rychlý start (API key/OAuth flow), vzorové požadavky, sandbox prostředí.
• Verzované portály: možnost přepínat dokumentaci mezi verzemi a prostředími (produkční/staging/sandbox).

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

• Idempotentní operace s Idempotency-Key pro POST požadavky, bezpečné opakování (retry).
• Stránkování (cursor/offset), filtrování a řazení; popsat limity a determinismus výsledků.
• Rate limiting a hlavičky (Retry-After, X-RateLimit-*); doporučit strategie backoffu.

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: 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 (komplikuje generování SDK a vytváření linků).
• Nekonzistentní chybové kódy, směšování doménových a technických chyb.
• Přetížení query parametrů mí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é narušuje 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á (produktoví manažeři), bezpečnostní (IAM/infosec).
3. Lint a validace – automatické kontroly stylu, názvosloví, souladu s předpisy.
4. Publikace – portál, verze, changelog, migrační průvodce.
5. Údržba