OpenAPI dokumentácia

OpenAPI specifikace je standardní formát pro popis RESTful API. Definuje jazykovo neutrálne rozhranie, ktoré umožňuje objavovanie a popis API z hľadiska svojich koncových bodov (endpointov), vstupných/výstupných parametrov, autentizácie, hlavičiek a ďalších detailov. Je to nástroj pre návrh, stavbu, dokumentáciu a použitie RESTful webových služieb, ktorý je kompatibilný s rôznymi technológiami a platformami. Posledná verzia OpenAPI je 3.0+, ktorú využíva i systém ABRA Gen.

Hlavný rozcestník OpenAPI dokumentácie systému ABRA Gen je k dispozícii tu:

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

Príklad vyvolania dokumentácie v online nástroji Swagger Editor ku kontroleru /firms.

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

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

Zobrazenie pomocou modelov nie je vo formáte OPenAPI, ale vo formáte JSON.

Š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:

Položka Popis
x-abra-bo-class-name Pokiaľ je táto položka vyplnená, ide o objektový kontroler. Pokiaľ nie je, ide o funkcionálny kontroler.
x-abra-field-enumeration

V tejto položke sú uvedené informácie o možných hodnotách výpočtových polí. Obsahuje subpoložky x-value (hodnota) a x-caption (popis), ktoré reprezentujú možné hodnoty, ktoré položka môže nadobúdať. 

"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

Viac viď PDF príručka použitie OpenAPI dokumentácie. Prípadne návod Ako zobraziť dokumentáciu Web API v nástroji Swagger UI, resp. Swagger Editor.