Swagger, resp. OpenAPI dokumentácia

OpenAPI špecifikácia, predtým známa ako Swagger, je štandardný formát pre 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

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.

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.