OpenAPI dokumentace

Hlavní rozcestník OpenAPI dokumentace 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}/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.

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

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