OpenAPI dokumentace REST API systému IS FLORES

Open API je standardní definice Web API, pomocí níž je API podrobně popsáno, tj. jaké má resourcy a co je na nich možné provádět za operace atd.

Naleznete v ní mj.:

  • definice všech BO a všech resourců
  • zdokumentované všechny metody, které je možno na resourcech použít
  • typy chyb, které Web API vrací
  • apod.
ClosedEndpoint & autentizace

OpenAPI dokumentace je dostupná pod resourcem "/{connection}/api-docs/swagger.json".

K autentizaci je možné použít dvě možnosti:

  • buď standardní mechanismus přihlášení pomocí Authorization headeru (viz Autentizace uživatele Web API)
  • nebo speciální možnost zavedenou kvůli načítání dokumentace do swagger-ui – query parametr "auth", jehož hodnotou je base64 (přihl. jméno:heslo), jako je tomu v případě Authorization headeru

    Musí to být navíc URL zakódováno.

ClosedSwagger-UI

Swagger-UI je nástroj sloužící k vizualizaci vygenerované dokumentace. Ke stažení je k dispozici např. zde:

git checkout https://github.com/swagger-api/swagger-ui.git

Ze staženého balíčku budeme potřebovat obsah podsložky "swagger-ui/dist" (dist obsahuje "zkompilovanou" verzi Swagger-UI).

K provozu aplikace Swagger-UI můžeme využít například PHP built-in server, který spustíme následovně:

php –S localhost:8090

PHP built-in server musí běžet na jiném portu, než na kterém poslouchá Supervisor (viz konfigurace Supervisora).

Nechť váš Supervisor běží např. na defaultním portu 8080. PHP built-in server tedy spustíme např. na portu 8090. Pokud byste měli stažený Swagger-UI uložený např. v cestě C:\API\swagger-ui a PHP webový server v cestě C:\API\php-5.6.25-Win32-VC11-x86\, mohla by dávka pro spuštění aplikace Swagger-UI umístěná v C:\API\ vypadat následovně:

cd swagger-ui\dist
..\..\php-5.6.25-Win32-VC11-x86\php.exe -S localhost:8090

PHP server bude po spuštění touto dávkou zobrazovat webový obsah umístěný ve "výchozí" složce, kterou bude C:\API\swagger-ui\dist:

PHP 7.2.7 Development Server started at Tue Jul 31 16:04:29 2018
Listening on http://localhost:8090
Document root is C:\API\swagger-ui\dist
Press Ctrl-C to quit.

Následně je třeba ve webovém prohlížeči přejít na adresu s obsahem, který webový server zobrazuje. Tj. zadat do webového prohlížeče adresu s příslušným portem:

localhost:8090

Poté, co server vrátí odpověď, do adresního řádku (nahoře) zadat adresu endpointu vč. URL zakódovaných "auth" údajů, jak bylo řečeno výše. Tj. např.:

http://localhost/data/api-docs/swagger.json?auth=U3VwZXJ2aXNvcjo%3D

Pokud máte nakonfigurovaného Supervisora na jiný port než defaultní port 80 (viz port v sekci "main_server" v konfiguraci Supervisora), je třeba samozřejmě uvést i příslušný port, na kterém poslouchá server. Tj. např. v případě portu 81:

http://localhost:81/data/api-docs/swagger.json?auth=U3VwZXJ2aXNvcjo%3D

Stanou se 2 věci:

  • Za cca 20s se vygeneruje definice (při dalších dotazech je cachovaná, takže je vracena instantně po dobu cca 15 minut nebo restartu aplikačního serveru)
  • Prohlížeč bude výslednou definici v závislosti na použitém hardware cca 2 minuty zpracovávat

Po vygenerování jsou zobrazeny všechny endpointy, ke každému z nich je k dispozici model vraceného/přijímaného objektu a popis. Zde si můžete např. dohledat, pod jakým resourcem je k dispozici faktura vydaná apod.:

Můžete si zobrazit datový model, typy chyb na daném BO apod.:

Pokud by vyvstala potřeba prohlédnout si definici BO napřímo (tj. JSON), tak struktury jednotlivých BO (modely) jsou k dispozici pod resourcem "/{connection}/api-docs/model/{název modelu}", kde "název modelu" je název BO v jednotném čísle, např.: "issuedinvoice". (Pozor, při dotazování nezapomenout na autentizaci.)

U modelů jsou v popisech fieldů BO záměrně označeny persistentní položky, jelikož ty jsou ve výchozím stavu vraceny při dotazech na kolekce BO.

Uživatelsky definovatelné položky ve výchozích dotazech na kolekce BO vraceny nejsou.

Pro používání OpenAPi je prozatím zapotřebí mít spuštěný aplikační server. (Tj. mít v nexus.cfg v části [Client] nastaveno Local na hodnotu 0.)