OpenAPI

Překládejte vysvětlující pole v souborech YAML pro OpenAPI 3.x a zachovejte cesty, identifikátory operací i odkazy beze změny.

Dokument OpenAPI propojuje strojově čitelný kontrakt API s vysvětleními pro jeho uživatele. Obslužná rutina souborů yaml-openapi vybírá pole title, description a summary podle jejich umístění v souboru YAML pro OpenAPI 3.x. Cesty, ID operací a odkazy zůstávají beze změny.

Zachovejte kontrakt API beze změny #

V tomto příkladu si operace zachovává svou identitu, zatímco její vysvětlení může být v různých jazycích:

yaml
openapi: 3.0.3
info:
  title: Order service
  version: 1.0.0
paths:
  /orders:
    get:
      operationId: listOrders
      summary: List your orders
      responses:
        "200":
          description: Orders retrieved

Obslužná rutina vybírá název, shrnutí a popis odpovědi. /orders, listOrders a 1.0.0 zůstávají beze změny. Výběr zahrnuje také informační pole, popisy tagů a externí dokumentace, popisy cest a popisná pole v rozpoznaných kontejnerech schémat a operací.

Zkontrolujte příklady a výchozí hodnoty, které mají v těchto kontejnerech podobu objektů. Vybrána může být i vnořená vlastnost s názvem title, description nebo summary, a to i tehdy, když představuje ukázková přenášená data. Ostatní hodnoty schématu, například běžné řetězce ve výčtech a hodnoty $ref, zůstávají beze změny.

Parser vyžaduje mapování YAML s verzí openapi, která začíná na 3.. Swagger 2.x, dokumenty bez uvedené verze i jiné verze odmítne. Soubor OpenAPI ve formátu JSON se nevybere jen proto, že OpenAPI tento formát podporuje; tato obslužná rutina je určena pro YAML.

Opětovné sestavení a využití překladů #

Aktuální zdroj určuje strom specifikace. Stávající znění se páruje podle identity popisného pole a jeho výskytu; při párování se zohledňuje také identita operace. Změněné zdrojové popisy je nutné znovu přeložit, zatímco u nezměněných polí, která se podaří spárovat, lze znovu použít cílové znění.

Serializátor YAML dokument znovu sestaví a může přitom sjednotit formátování. Udržujte předchozí zdrojové a cílové specifikace ve vzájemném souladu a kontrolujte přesuny polí i opakující se popisy, které mají vliv na opětovné použití překladů.

Vyberte obslužnou rutinu pro specifikaci #

V konfiguraci souborů pro CLI explicitně vyberte yaml-openapi pro .yaml nebo .yml. Samotná přípona nestačí k rozlišení specifikace API od katalogu aplikace. Obecná obslužná rutina YAML by vybrala mnohem více řetězců; YAML s jazyky v kořeni má jiné požadavky na obalovou strukturu.

K výběru souborů a nastavení cílových cest použijte konfiguraci CLI nebo GitHub. Překlad omezený na konkrétní klíče není v CLI pro OpenAPI dostupný.

Ověřte kontrakt a přečtěte si popisy #

Ověřte znovu sestavený dokument pomocí svých nástrojů pro OpenAPI a porovnejte cesty, ID operací, odkazy, povinná pole a hodnoty schématu se zdrojem. Poté si v kontextu tohoto kontraktu přečtěte zobrazené popisy. Popis odpovědi, který mění podmínku nebo příslib, může vývojáře uvést v omyl, i když specifikace zůstává platná.