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í dokumentaci lze pak získat takto:

GET {server-api}:{port}/{spojeni}/api-docs/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.

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

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

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

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:

"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

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í.