Swagger documentation customisation

Swagger is a popular software framework that helps developers build RESTful Web services through their entire lifecycle, from design and documentation, to test and deployment. This post focuses on how to incorporate the API documentation generated through Swagger inside an HTML page hosted from another web application.

One of the main features of Swagger is producing interactive documentation for a RESTful API. Swagger can be used in conjunction with a multitude of different languages and frameworks. It will always produce two different outputs inside the same web application hosting the API:

A default HTML page having a standard Swagger style. (Europe PMC Annotations API Swagger standard html page)
A JSON file that will contain the description of the generated documentation (Europe PMC Annotations API documentation descriptor)

The goal is to display the Swagger HTML documentation inside an external web site page adapting Swagger’s default style to the one of the external site. One option could be to copy manually the HTML produced from Swagger inside the external site page. The obvious disadvantage of this solution is that it will be necessary to keep the Swagger code contained into the RESTful API web application in sync with the content shown in the external page, each time a modification to the documentation is performed. Ideally the content of the Swagger documentation should be displayed in the external page loading it dynamically from the RESTful API application, to avoid synchronization issues. To this end it is necessary to perform the following steps:

Download the Swagger UI folder from: GitHub
Once downloaded, create a swagger-ui folder in the resources folder of the external web application and add the contents downloaded from the Github Repository in this folder.
In the header of the html page where to incorporate the Swagger documentation import the following CSS and javascript files:

<head>
         .....
  	<link href='./swagger-ui/css/typography.css' media='screen' rel='stylesheet' type='text/css'/>
  	<link href='./swagger-ui/css/reset.css' media='screen' rel='stylesheet' type='text/css'/>
  	<link href='./swagger-ui/css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
  	<link href='./swagger-ui/css/reset.css' media='print' rel='stylesheet' type='text/css'/>
  	<link href='./swagger-ui/css/print.css' media='print' rel='stylesheet' type='text/css'/>

  	<script src='./swagger-ui/lib/object-assign-pollyfill.js' type='text/javascript'></script>
  	<script src='./swagger-ui/lib/jquery-1.8.0.min.js' type='text/javascript'></script>
  	<script src='./swagger-ui/lib/jquery.slideto.min.js' type='text/javascript'></script>
  	<script src='./swagger-ui/lib/jquery.wiggle.min.js' type='text/javascript'></script>
  	<script src='./swagger-ui/lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
  	<script src='./swagger-ui/lib/handlebars-4.0.5.js' type='text/javascript'></script>
  	<script src='./swagger-ui/lib/lodash.min.js' type='text/javascript'></script>
  	<script src='./swagger-ui/lib/backbone-min.js' type='text/javascript'></script>
  	<script src='./swagger-ui/swagger-ui.min.js' type='text/javascript'></script>
  	<script src='./swagger-ui/lib/highlight.9.1.0.pack.js' type='text/javascript'></script>
  	<script src='./swagger-ui/lib/highlight.9.1.0.pack_extended.js' type='text/javascript'></script>
  	<script src='./swagger-ui/lib/jsoneditor.min.js' type='text/javascript'></script>
  	<script src='./swagger-ui/lib/marked.js' type='text/javascript'></script>
  	<script src='./swagger-ui/lib/swagger-oauth.js' type='text/javascript'></script>
 </head>
   .....

In the body of the same html page it is necessary to place a div where the Swagger documentation will be placed and then call the Swagger specific function to load the relevant API documentation

 <body>
	.....
	
	<div id="swagger-ui-container"></div>
	
	<script type="text/javascript">
	
		jQuery(function () {
			hljs.configure({
				highlightSizeThreshold: 5000
			});

			// Pre load translate...

			if(window.SwaggerTranslator) {
				window.SwaggerTranslator.translate();
			}
	  
			window.swaggerUi = new SwaggerUi({
				url: "https://www.ebi.ac.uk/europepmc/annotations_api/v2/api-docs.json",
				dom_id: "swagger-ui-container",
				supportedSubmitMethods: ['get'],
				docExpansion: "list",
				jsonEditor: false,
				defaultModelRendering: 'example',
				showRequestHeaders: false,
				showOperationIds: false,
				validatorUrl:null
			});

			window.swaggerUi.load();
		});
	</script>  
	
	...
</body>

The javascript object SwaggerUi will load the API documentation described through the url property and will place it inside the dom identified by the dom_id property value. Below are details of the properties that can be set to the SwaggerUi object:

Parameter Name	Description
url	The url pointing to `swagger.json` (Swagger 2.0) or the resource listing (earlier versions) as per OpenAPI Spec.
authorizations	An authorization object to be passed to swagger-js. Setting it here will trigger inclusion of any authorization or custom signing logic when fetching the swagger description file. Note the object structure should be `{ key: AuthorizationObject }`
spec	A JSON object describing the OpenAPI Specification. When used, the `url` parameter will not be parsed. This is useful for testing manually-generated specifications without hosting them. Works for Swagger 2.0 specs only.
validatorUrl	By default, Swagger-UI attempts to validate specs against swagger.io's online validator. You can use this parameter to set a different validator URL, for example for locally deployed validators (Validator Badge). Setting it to `null` will disable validation. This parameter is relevant for Swagger 2.0 specs only.
dom_id	The id of a dom element inside which SwaggerUi will put the user interface for swagger.
booleanValues	SwaggerUI renders boolean data types as a dropdown. By default it provides a 'true' and 'false' string as the possible choices. You can use this parameter to change the values in dropdown to be something else, for example 0 and 1 by setting booleanValues to new Array(0, 1).
docExpansion	Controls how the API listing is displayed. It can be set to 'none' (default), 'list' (shows operations for each resource), or 'full' (fully expanded: shows operations and their details).
apisSorter	Apply a sort to the API/tags list. It can be 'alpha' (sort by name) or a function (see Array.prototype.sort() to know how sort function works). Default is the order returned by the server unchanged.
operationsSorter	Apply a sort to the operation list of each API. It can be 'alpha' (sort by paths alphanumerically), 'method' (sort by HTTP method) or a function (see Array.prototype.sort() to know how sort function works). Default is the order returned by the server unchanged.
defaultModelRendering	Controls how models are shown when the API is first rendered. (The user can always switch the rendering for a given model by clicking the 'Model' and 'Model Schema' links.) It can be set to 'model' or 'schema', and the default is 'schema'.
onComplete	This is a callback function parameter which can be passed to be notified of when SwaggerUI has completed rendering successfully.
onFailure	This is a callback function parameter which can be passed to be notified of when SwaggerUI encountered a failure was unable to render.
highlightSizeThreshold	Any size response below this threshold will be highlighted syntactically, attempting to highlight large responses can lead to browser hangs, not including a threshold will default to highlight all returned responses.
supportedSubmitMethods	An array of of the HTTP operations that will have the 'Try it out!' option. An empty array disables all operations. This does not filter the operations from the display.
oauth2RedirectUrl	OAuth redirect URL
showRequestHeaders	Whether or not to show the headers that were sent when making a request via the 'Try it out!' option. Defaults to `false`.
jsonEditor	Enables a graphical view for editing complex bodies. Defaults to `false`.

Now it is possible to customize the standard style of the Swagger documentation tweaking both the default Swagger css and the site application css as required. An example of the result can be found at Europe PMC Annotations API documentation page

Written on 27 November 2017, by Francesco Talo', in Documentation

Europe PMC Tech Blog

Swagger documentation customisation