Dokumentace Web API

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

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

Vrácená data z endpointu /api-docs/openapis obsahují kromě identifikátoru kontroleru (CLSID) také identifikátor třídy business objektu (BOCLSID), pokud se jedná o objektový kontroler. To umožňuje jednoduše navázat na další struktury či metadata business objektů definovaných v systému.

Kompletnú dokumentáciu je potom možné získať takto:

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

V OpenAPI dokumentácii nájdete:

• definícia všetkých BO a zdrojov
• zdokumentované metódy, ktoré je možné na zdrojoch použiť
• a. i.

Oproti predošlej dokumentácie je teraz možné dokumentáciu získať nielen ako jeden veľký JSON, ale i distribuovane vo viacerých čiastkových JSONoch. Rozdelenie do viacerých súborov je realizované dvoma spôsobmi

1. podľa typu časti openapi - paths, schemas...
2. podľa endpointu/kontrolera - typicky teda za všetky cesty, ktoré patria k zvolenému BO

Napr. čiastkovú dokumentáciu za endpoint firmy potom získame zavolaním:

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

Defaultne je openapi vrátené v distribuovanej forme, tzn. všetky jeho časti sú v samostatných súboroch, ktoré je možné získať dopytom na príslušný endpoint. Pokiaľ je chcené, aby bolo openapi vrátené v jednom súbore je to možné vynútiť použitím query parametra distrib=false. Openapi 3 je v oboch režimoch kompatibilné s nástrojmi Swagger UI, prípadne Swagger Editor, ktoré odporúčame pre užívateľské prehliadanie dokumentácie. V nich je však nutné z výkonostných dôvodov prechádzať dokumentáciu vždy len za vybraný kontroler.

Pro základní přehled dostupných kontrolerů a pro vizuální zobrazení dokumentace je možné použít také HTML rozhraní. Pokud klient požaduje výstup ve formátu text/html, lze využít následující endpointy:

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

Zobrazí se jednoduchá webová stránka s přehledem dostupných controllerů ve formě tabulky. Po kliknutí na konkrétní controller se otevře detailní dokumentace.

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

Zobrazí se stránka s dokumentací vybraného controlleru pomocí nástroje SwaggerUI.

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

Zobrazí se stránka s celkovou dokumentací všech controllerů v jednom zobrazení pomocí SwaggerUI. Tento výstup může být velmi rozsáhlý a při zobrazení v prohlížeči může dojít k přetížení paměti.

Pro tato zobrazení jsou použity dvě jednoduché HTML stránky:

• apidoc.html – stránka s přehledem všech dostupných controllerů a tabulkou.
• apidocdetail.html – stránka s vizualizací dokumentace vybraného controlleru pomocí SwaggerUI.

OpenAPI dokumentace definuje schémata pro jednotlivé business objekty (BO) a jejich vlastnosti včetně podpory:

• odkazů na jiné business objekty (referencí),
• kolekcí (seznamů objektů nebo hodnot),
• atributů readonly a writeonly určujících přístupová práva k dané položce,
• vlastních rozšíření specifických pro systém ABRA Gen (např. x-abra-field-enumeration).

Dotazování na OpenAPI dokumentaci podporuje parametr distrib, který ovlivňuje způsob vrácení dat:

• Při distrib=false (výchozí) je dokumentace vrácena jako jeden soubor.

• Při distrib=true je dokumentace vrácena ve formátu, který obsahuje pouze základní metadata a odkazy na jednotlivé části specifikace OpenAPI pomocí $ref. Jedná se o tzv. distribuovanou formu, kde jsou části jako paths, schemas a další zpřístupněny odděleně

  Tato struktura umožňuje načítání dokumentace po jednotlivých segmentech a je vhodná zejména pro interaktivní nástroje jako Swagger UI nebo Swagger Editor, které si mohou jednotlivé části dotáhnout dynamicky podle potřeby.

U jednotlivých endpointů může být uveden atribut deprecated, který signalizuje plánované odstranění nebo změnu. Atribut zároveň obsahuje informaci o verzi, ve které ke změně dojde.

Zobrazení dokumentace pomocí integrovaného SwaggerUI zohledňuje všechny výše uvedené vlastnosti a umožňuje jejich interaktivní prozkoumání.

Zoznam dostupných modelov je k dispozícii na endpointe:

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

Štruktúru dát v danom modeli potom získame prostredníctvom:

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

Popis vybraných položiek:

"x-abra-field-enumeration": [
    {
        "x-caption": "Hlavná činnosť",
        "x-value": 0
    },
    {
        "x-caption": "Vedľajšia činnosť",
        "x-value": 1
    }
]

GET http://localhost:81/demodata/api-docs/model/absence