Jak zobrazit dokumentaci Web API

Připravili jsme pro vás postup, jak zobrazit dokumentaci Web API pomocí nástrojů Swagger UI a Swagger Editor. Obecné inforamce o dokumentaci Web API naleznete v kap. Swagger, resp. OpenAPI dokumentace

1. Předpoklady

• Zobrazení dokumentace Web API budeme zkoušet na spojení s názvem demodata na localhostu, portu 80.
• V konfiguračním souboru Nexus.CFG máme v sekci [Client] nastavenou hodnotu parametru Local na 0.
• Bude spuštěn aplikační server.

• Bude spuštěno Web API:

  V instalačním adresáři ABRA Gen vyvoláme jako administrátor Powershell Web API a zadáme:

  .\APIServer.ps1 -Action app

  Pokud již Web API beží, nemusíme je spouštět. Na již nakonfigurovaném, funkčním a běžícím Web API se navíc může lišit název spojení, případně port.

2. Zobrazení Web API v nástroji Swagger UI

1. Stáhneme nástroj Swagger UI.

2. Nástroj rozbalíme do libovolné složky.

   C:\APIDOC\swagger-ui-5.17.14\

3. V cestě ..\swagger-ui-5.17.14\dist\ zeditujeme soubor swagger-initializer.js.

4. Hodnotu url: změníme např. na http://localhost:80/demodata/api-docs/openapi/firms

   Jako výchozí endpoint nedáváme přímo /openapi. Dokumentace by se totiž načítala extrémně dlouho.

5. Při otevření souboru index.html ve stejné složce se nám obrazí dokumentace k endpointu /firms (je třeba chvíli počkat).
6. Následně můžeme do vyhledávacího řádku Swagger UI zadat libovolný endpoint a zobrazit tak jeho dokumentaci.

Ve Swagger UI můžeme API dotaz i vyzkoušet. K tomu budeme potřebovat autentizační údaje zakódované do base64 pro parametr auth. Jak postupovat viz Query parametr auth.

1. Rozbalíme požadovaný endpoint a klineme na tlačítko Try it out:

   

2. Zadáme hodnotu parametru auth:

   

   Hodnota U3VwZXJ2aXNvcjoxMjM0NQ z obrázku výše odpovídá příhlašovacímu jménu Supervisor a heslu 12345 zakódovanému do base64.

3. Následně provedeme dotaz tlačítkem Execute a v poli Response body se nám zobrazí výsledek dotazu:

   

3. Zobrazení Web API v nástroji Swagger Editor

K zobrazení dokoumentace lze využít i online nástroj Swagger Editor.

Přejdeme na stránky Swagger Editoru. Z menu vybereme položku File > Import a vložíme endpoint, ke kterému chceme získat dokumentaci. Např. http://localhost:80/demodata/api-docs/openapi/firms. Je třeba chvíli počkat, než se kompletní dokumentace načte.