Step-by-Step Guide to Swagger Inspector, Hub & UI

Swagger is a RESTful API documentation tool based on OpenApi Specification. It is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services (API). These documentation is so easy to understand that it can easily be interpreted by the clients without any server side code knowledge.

Swagger consists of three tools in its system, these tools are used to document parameters, methods and models. They are as follow in their sequential order for execution:-

~ Swagger Inspector
~ Swagger Hub
~ Swagger UI

Swagger Inspector
When any web service (API) is developed, the very first step is to implement that API into Swagger Inspector for implementing that web service (API) into the Swagger Inspector, one need to have an account. After login successfully :

1. User needs to select desired method.

2. User needs to enter URL of the web service (API) in the text field which says “Any HTTP resource or the URL of an OpenAPI / WSDL definition”.

3. User can add new parameters and its value for the request.

4. Also, if the user needs to add more parameters than he/she can click on “ADD NEW PARAMETER”.

5. After adding parameters, user need to enter “Headers”.

6. Also, if the user needs to add more Headers than he/she can click on “ADD NEW HEADER”.

7. After adding Headers, user need to enter “Authentication”. There are three options to select from as Authentication.

8. After adding Authentication, if user selects “POST, PUT, DELETE, PATCH” as method than Body is enabled because only these methods support Body for request.

9. If the Body is enabled, than user needs to enter request Body. This Body will be a JSON code.

10. After adding the Body, user needs to click on send button.

11. In response, final output of the request is shown in the “Response” area.

12. All the entries of Send Request are stored in the History section. From there user can use all the previously executed API’s by just clicking on the record. User needs to check the box shown beside the API name (URL) to add it to any particular collection, or else user can create new collection from here too.

13. User can view all the previously created collections and also view all the API’s added into that collections.

14. User needs to create definition for further process in Swagger Hub. So user needs to export this definition to Swagger 2.0 or 3.0, which can be done from here.

Swagger Hub
When any web service (API) is developed, the second step is to generate documentation of that particular web service (API). For generating the documentation Swagger Hub is used. These documentations are written in YAML language inside Swager Hubs editor. These is pre-written in the Swagger Hub, which is when we create definition from Swagger Inspector.

1. Also, if a user wants to create any new documentation than he/she can create it directly without using definition created from Swagger Inspector.

2. By clicking “Create New API”, user is able to create new API documentation by filling up the form.

3. By clicking “Create New API”, user user needs to fill up the data as per his/her requirements.

4. Sample code

Swagger UI
The very last step of Swagger Web Service (API) documentation is Swagger UI, it is the viewing / displaying of the Web Services (API) in the browser. There are two methods to view documentation.

~ Online
1. It can be viewed by clicking on Design View and selecting Preview Docs. It will open new tab and the Web Service (API) documentation will be shown.

2. To execute the Web Service (API) user needs to click on “Try it out”, by doing so user will be able to edit the request body & headers.

3. To run Web Service (API) after finalizing request body and headers, user needs to click on “Execute” button. Based on the request it will show response.

~ Offline
To view the Web Service (API) in offline mode, user needs to download Swagger UI in their System. It can be downloaded from this page https://swagger.io/tools/swagger-ui/download/

There are some prerequisites to run Swagger UI offline
~ XAMPP
~ Downloaded zip of Swagger UI

1. After installing XAMPP, user needs to be directed to the following directory
/var/www/html

2. In that folder create new folder named “swagger-ui”. After creating this folder extract the downloaded zip file in this folder and delete the zip file.

3. Open that extracted folder and go to “dist” folder, in that folder copy all the files in “dist” folder and paste it in the main “swagger-ui” folder and delete rest of the content.

4. Now go to the Swagger Hub source code and export the code to the JSON file.

5. Now paste that downloaded JSON file to the following directory
/var/www/html/swagger-ui

6. Now open “index.html” and edit the url in the “index.html” to the file name of JSON.

7. Now open your browser and go to the URL which you set in the XAMPP, it will open your Web Service (API). To run the Web Service (API) click on “Try it out” so that you can enter request body & headers as per the need

8. To run Web Service (API) after finalizing request body and headers, user needs to click on “Execute” button. Based on the request it will show response.

Conclusion
Following all these steps sequentially one can perfectly obtain a API Service Testing documentation. It is best suited for the QA testers and the clients.