OpenAPI: popis REST API v JSON a YAML

Jak číst dokument OpenAPI

openapi je verze specifikace; info.version verze tvého API. V servers je základ adresy a paths obsahuje relativní cesty s operacemi jako get nebo post. parameters popisují hodnoty v cestě, query, hlavičce či cookie; requestBody je samostatné tělo požadavku. responses popisují možné odpovědi podle statusu.

Nejdřív si stanov operaci a reálná data. Níže katalog dovoluje veřejné čtení jedné knihy a přihlášené vytvoření. Doména example.cz je ilustrační; na adrese neběží ukázkový server.

Úplný popis API pro čtení a vytvoření knihy

openapi.json — OpenAPI 3.1.0

{
  "openapi": "3.1.0",
  "info": {
    "title": "Katalog knih",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://example.cz/api"
    }
  ],
  "paths": {
    "/knihy/{id}": {
      "get": {
        "operationId": "najdiKnihu",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Nalezená kniha",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Kniha"
                }
              }
            }
          },
          "404": {
            "description": "Kniha neexistuje",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Chyba"
                }
              }
            }
          }
        }
      }
    },
    "/knihy": {
      "post": {
        "operationId": "vytvorKnihu",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "nazev"
                ],
                "properties": {
                  "nazev": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Vytvořeno",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Kniha"
                }
              }
            }
          },
          "401": {
            "description": "Chybí platné přihlášení"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Kniha": {
        "type": "object",
        "required": [
          "id",
          "nazev"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1
          },
          "nazev": {
            "type": "string",
            "minLength": 1
          }
        },
        "additionalProperties": false
      },
      "Chyba": {
        "type": "object",
        "required": [
          "zprava"
        ],
        "properties": {
          "zprava": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  }
}

/knihy/{id} musí mít parametr id s in: "path" a required: true. Pole parameters a objekt properties mají jinou funkci; parametr se nestává položkou JSON těla. Odpovědi mají povinný popis. U médií v content je schéma skutečně přenášené hodnoty.

Znovupoužití, typy a autentizace

components.schemas.Kniha se používá v obou úspěšných odpovědích pomocí $ref. Klíč components sám nic nezapíná: komponenta se projeví až odkazem. V OAS 3.1 jsou Schema Objects založené na JSON Schema 2020-12; required určuje přítomnost a type typ. Nullable hodnotu vyjádři například polem typů string a null, nikoli slepým přenesením nullable z OAS 3.0.

securitySchemes definuje bearer mechanismus a security jej vyžaduje pro POST. bearerFormat: "JWT" je popisná nápověda. Server musí podpis, claims i právo vytvořit knihu ověřit sám. GET v této ukázce žádné security nepožaduje, protože není ani globální požadavek.

Co klient pošle a co server vrátí

Ilustrace výměny, nikoli serverový log

GET /api/knihy/1 HTTP/1.1
Host: example.cz
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{"id":1,"nazev":"XML"}

Neplatná odpověď podle schématu Kniha

{"id":"1","nazev":"XML"}

Řetězcové id je syntakticky platný JSON, ale neodpovídá integer. Pro 404 příslušné schéma naopak očekává zprávu; ověřování všech statusů podle schématu 200 by bylo chybné. Pro POST klient pošle pouze název a server přidělí id. Dokumentace musí odpovídat skutečnému chování serveru, včetně chybových odpovědí.

Tři kroky ověření

Ověř JSON nebo YAML syntax. Pro JSON lze použít zdejší nástroj.
Dokument otevři v nástroji podporujícím OpenAPI 3.1, například Swagger Editor. Ověř reference a strukturu operací, nikoli pouze obarvený text.
Pro skutečný server proveď požadavek a porovnej status, Content-Type i tělo s vybranou odpovědí. Zkus existující i chybějící id a POST bez přihlášení.

JSON Schema validátor umí ověřit data proti vybranému schématu. Samotné vložení celého OpenAPI dokumentu do datového editoru neprovede validaci API. Pro samostatnou kontrolu Kniha zkopíruj její schéma; u odkazů na externí schémata musí validátor umět najít a načíst odpovídající soubory.

Verze, chyby a zdroje

Příklad je záměrně připnutý k OpenAPI 3.1.0. Přehled publikovaných verzí najdeš v oficiální aktuální specifikaci. Před migrací ověř podporu parseru, editoru, generátoru a testů požadavků a odpovědí podle dokumentace; změna čísla openapi není převod všech konstrukcí.

Nezaměňuj query parametr a tělo požadavku.
Používej jednoznačné operationId, pokud generuješ klienta.
Ukázky musí odpovídat schématu; popis sám typy nevynucuje.
Po změně komponenty ověř všechny operace, které ji používají.

Navazuje HTTP API, skládání schémat a JWT.