Swagger - How to use

[mohsenomidi]

Dears,

I am a basic user of swagger, and i don't know the procedure of using the swagger.

First: In Pistache i found the rest_description.cc to implement the swagger, but in the git repository there is no file "banker-api.json" to understanding the JSON structure and the file contents. and also octal uses the "swagger-ui-2.1.4/dist" inside the code, in the git page of swagger-ui there is no version 2.1.4 and current version of swagger is 3.18.3 (::now() = 11/01/2020).

Second: there is another library called swagger-codegen it seems there is an integration with Pistache or similar alternative implementation ( in examples i see the pistache server) now i am confusing

what is the different between these libraries and which one is usable to create swagger(the API help UI) for the web services ?

PS: sorry for about my less knowledge about the swagger, i am not the UI expert and mainly i just working in backed side, but now i should use the swagger as a manual page for the internal developed API's

[mohsenomidi]

Hi every body,

after some try i found these information that shows the how Pistache support swagger :

in example rest_description.cc we setup the server to serve the swagger-ui-dist and the path of the URL that should call from browser this path point to the swagger-ui-dist directory

you should download the swagger-ui-dist and put it into the directory that mentioned in "uiDirectory" in start function.

now the url you should called is the server address plus the uiPath route ( in example file is /doc) for example 192.168.1.10/doc

now the Pistache acts as the webserver to display swagger ui.

there is another parameter, the apiPath : apiPath is represent the JSON that swagger can read and parse it in its UI structure, that shows the api functions, routes and any thing you mentioned in the code visually.

banker-api.json will be automatically generated during the pistache rest_descriptor starts.

you can see the JSON file in browser with your link (example http(s)://192.168.1.10/banker-api.json)

if this file pass to the swagger UI the entire swagger UI page will be generated.

[mohsenomidi]

the point about Swagger-Codegen :

Swagger Codegen can simplify your build process by generating server stubs and client SDKs for any API, defined with the OpenAPI (formerly known as Swagger) specification, so your team can focus better on your API’s implementation and adoption.

it mean this getting the Swagger JSON file and create server & client based on your preferred programming language it also supports the pistache (currently the codegen version is not supporting the last pistache version. you should add some namespace and change make files and remove some old flags of pistache to compatible with the last version)

it does not do the actions of rest_description.cc. it means nothing related to descriptor here.

Now i get whole story.. may this thread will usable for others does not familiar with swagger, and need to be use it in their code.