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+. ABRA Web API je postavena na specifikaci swagger 2.0 , ale vzhledem k tomu, že OpenAPI je oficiální nástupce specifikace Swagger, budeme se držet termínu OpenAPI.
OpenAPI dokumentace je dostupná prostřednictvím endpointů:
GET /{spojení}/api-docs
GET /{spojení}/api-docs/swagger.json
V OpenAPI dokumentaci naleznete:
- definice všech BO a zdrojů
- zdokumentované metody, které je možno na zdrojích použít
- aj.
Pro přístup k API dokumentaci lze využít webové aplikace apiDoc-ABRA-Gen a apisandbox.
Aplikaci apiDoc-ABRA-Gen provozujeme nad vlastními daty a je tedy třeba mít správně nakonfigurovaný a spuštěný ApiServer. Aplikaci je možné provozovat i offline (webová aplikace nedokáže navíc přistupovat k ApiServeru, který není přístupný z internetu).
Zde uvádíme příklad přihlášení pro spojení localhost:8082/data a uživatele Supervisor.
Pokud bychom zadali přihlašovací údaje chybně, je třeba pro opětovné vyvolání přihlašovacího dialogu smazat data v {user}\AppData\Local\ExeOutput.
Dříve byla pro prohlížení OpenAPI dokumentace doporučován nástroj Swagger-ui. Ten však s nárůstem objemu swagger.json přestal být použitelný.