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}/api-docs/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 použí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í.

Kromě dokumentace business objektů poskytuje API také statické popisy Stav na serveru. Popisují pomocí OpenAPI speciální objekty dostupné pouze ve stavu na serveru

Pro získání seznamu všech speciálních objektů a jejich popisů slouží endpoint:

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

Pro získání detailního popisu konkrétního objektu slouží hodnota Detail:

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

Kromě dokumentace business objektů poskytuje API také statické popisy pro importní manažery (IM). Tyto popisy obsahují seznam všech parametrů IM, jejich typy a další příznaky, přičemž struktura popisu je stejná jako u business objektů.

Pro získání seznamu všech zaregistrovaných importních manažerů a jejich popisů slouží endpoint:

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

Pro získání detailního popisu konkrétního importního manažera použijte jeho název v URL:

GET {server-api}:{port}/{spojeni}/api-docs/importmanager/<nazev_importniho_managera>

GET http://localhost:80/demodata/api-docs/importmanager/receivedordertobillofdelivery

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

Skriptovací systém byl rozšířen o podporu automatické dokumentace API funkcí, kterou lze volat přímo z API. Dokumentace je registrována přímo v balíčcích skriptů společně s implementací API funkcí.

Více informací včetně příkladu najdete na stránce Příklady pokročilého skriptování.