Use Swagger UI for showing interactive API documentation

Following Swagger post I showed how to configure Swagger with Spring project. In this blog I will demonstrate using Swagger UI for showing interactive documentation.

Swagger UI is part of the Swagger project and it allows you to generate, visualize and consume API. It is package which basically consist of html, css and javascript, and parses the json output generated from application code scanning. This scanning and configuration was explained in following post.

Swagger UI Setup can be downloaded from "here".

Copy the files to a Dynamic Web project in eclipse and paste the content from "dist" folder to WebContent as shown below.




Here I am using tomcat server to host this UI application. By doing so it will be easy to share the API application with other user. It shows following UI. 

Please note that by default swagger will load the petstore Api details. I will cover customizing them in next point. 




Swagger UI presents very nice interactive tool, using which users can read the documentation, can see the exposed API, detailed input and output parameter, also they can test the API real time. This tool present by parsing the json output which was generated while scanning the API project. 

Above UI shows all the available API exposed in petstore application, method type supported and some basic details at top level. 

You can see entire API details after expanding the service  by clicking on the link. Below "/store/inventory" API has been expanded and you can see description of this API, what is response code returned when successful, at the last of the section you can see "Try it Out!" button, using which you can test the API. 

Response from the API will be shown in the same section below the button.

 

By default Swagger UI shows details pet store API, now if you want your custom build API to be listed, then few changes needs to be done in the above setup. Below I am going to explain the steps which needs to be done to customize the output.

• Ensure that application is completed with the swagger setup and json output is accessible when you access following url, "http://localhost:9081/SpringSwaggerDemo/v2/api-docs", this is the url for the sample api application  which i created, you need to change it as per your setup, but last part of URL remain same i.e. "/v2/api-docs".
• To load api documentation in the Swagger UI enter the above url in test field provided in top header section and press on "Explore" button.
• Application will parse json and it will display the content in below section. This temporary loads you custom API details.
• This url change will not be persisted in the UI code if you refresh the page it will be lost, so to persist the url change you need to modify the script code as shown below.
• Locate index.html file, open with editor do following changes. modify the url value to you API url as shown below. After this change launch the UI again, you will see by default application loads the API details.

  var url = window.location.search.match(/url=([^&]+)/);
  if (url && url.length > 1) {
     url = decodeURIComponent(url[1]);
  } else {
      //url = "http://petstore.swagger.io/v2/swagger.json"; // change this value to your API json url. 
      url="http://localhost:9081/SpringSwaggerDemo/v2/api-docs";
  }

• Check below UI where it shows the custom API details.

• Next I will explain some more customization's related to language and UI.

• Different Language support.
• Swagger support showing UI menu in different languages. To enable this change index.html file needs to be modified and you need to add following script files. These files comes with the package which you downloaded. Locate "lang" folder inside the project, you will find different language files which by default comes with package. If you need to enable French language, so following code needs to be added in the index.html file. 

  <script src="lang/translator.js" type="text/javascript"></script>
  <script src="lang/fr.js" type="text/javascript"></script>

• By default basic menu and other controls of Swagger UI will be converted to french language. Incase you have any other language for which file is not present then you need to create that file and place it inside this folder and include it in the html file.
• UI Customization
• Swagger UI can be customized and configured as per the organization and individual needs and requirements.
• Entire source code is provided, so any modification can be easily done. Generally following are the section in UI which needs to be modified like Header, Logo, Color theme, etc.
• To change the logo change the images inside "img" folder.
• To apply new css, modify the css or override by putting new css file which extends the style provided by swagger.
• To modify parsing logic and other logic modify js file inside lib folder.
• Below is one sample changes to UI I have done. You can see the difference between above UI and the modified UI.

I hope this will be helpful post for people looking to use swagger as API documentation tool using Swagger UI. This post will help you kick starting the process.

Share your feedback.