Swagger, resp. OpenAPI dokumentace

OpenAPI specifikace, dříve známá jako Swagger, je standardní formát pro popis RESTful API. Definuje jazykově neutrální rozhraní, které umožňuje objevování a popis API z hlediska svých koncových bodů (endpointů), vstupních/výstupních parametrů, autentizace, hlaviček a dalších detailů. Je to nástroj pro návrh, stavbu, dokumentaci a použití RESTful webových služeb, který je kompatibilní s různými technologiemi a platformami. Poslední verze OpenAPI je 3.0+, kterou využívá i systém ABRA Gen.

Hlavní rozcestník OpenAPI dokumentace systému ABRA Gen je k dispozici zde:

GET {server-api}:{port}/{spojeni}/api-docs/openapis

Kompletní dokumentaci lze pak získat takto:

GET {server-api}:{port}/{spojeni}/apidocs/openapi

V OpenAPI dokumentaci naleznete:

  • definice všech BO a zdrojů
  • zdokumentované metody, které je možno na zdrojích použít
  • aj.

Oproti dřívější dokumentaci je nyní možné dokumentaci získat nejenom jako jeden velký JSON, ale i distribuovaně ve více dílčích JSONech. Rozdělení do více souborů je realizováno dvěma způsoby

  1. dle typu části openapi - paths, schemas...
  2. dle endpointu/kontroleru - typicky tedy za všechny cesty, které patří ke zvolenému BO

Např. dílčí dokumentaci za endpoint firmy pak získáme zavoláním:

GET {server-api}:{port}/{spojeni}/api-docs/openapi/firms

Defaultně je openapi vraceno v distribuované formě, tzn. všechny jeho části jsou v samostatných souborech, které je možné získat dotazem na příslušný endpoint. Pokud je chtěné, aby bylo openapi vráceno v jednom souboru je to možné vynutit použitím query parametru distrib=false. Openapi 3 je v obou režimech kompatibilní s nástroji Swagger UI, případně Swagger Editor, které doporučujeme pro uživatelské prohlížení dokumentace. V nich je však nutné z výkonostních důvodů procházet dokumentaci vždy pouze za vybraný kontroler.

Příklad vyvolání dokumentace v online nástroji Swagger Editor ke kontroleru /firms.

Seznam dostupných modelů je k dispozici na endpointu:

GET {server-api}:{port}/{spojeni}/api-docs

Zobrazení pomocí modelů není ve formátu OPenAPI, ale ve formátu JSON.

Strukturu dat v daném modelu pak získáme přes:

GET {server-api}:{port}/{spojeni}/api-docs/model/<hodnota>

Popis vybraných položek:

Položka Popis
x-abra-bo-class-name Pokud je tato položka vyplněná, jedná o objektový kontroler. Pokud není, jedná se o funkcionální kontroler.
x-abra-field-enumeration

V této položce jsou uvedeny informace o možných hodnotách výčtových polí. Obsahuje subpoložky x-value (hodnota) a x-caption (popis), které reprezentují možné hodnoty, jež položka může nabývat. 

"x-abra-field-enumeration": [
    {
        "x-caption": "Hlavní činnost",
        "x-value": 0
    },
    {
        "x-caption": "Vedlejší činnost",
        "x-value": 1
    }
]
 
GET http://localhost:81/demodata/api-docs/model/absence

Více viz PDF příručka použití OpenAPI dokumentace. Případně návod Jak zobrazit dokumentaci Web API v nástroji Swagger UI, resp. Swagger Editor.