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.

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.