When creating software documentation, documenting your API in a clear, dynamic deliverable is key to helping end-users understand and effectively integrate with your application. Swagger is one of the most popular tools used to design, build, document, and use RESTful web services. Swagger includes automated documentation, code generation, and test-case generation, with dynamic “Try it out” functionality. Many of our users have existing API documentation in Swagger that they would like to incorporate in their HTML5 output that they are generating from MadCap Flare, but the typical question is, “How?”

Well, Swagger has created a tool called “Swagger UI” that allows you to visualize and interact with an API from a web page. Swagger UI is a collection of HTML, CSS, and JavaScript files that can port your existing Swagger API documentation seamlessly into your HTML5 output, retaining formatting, as well as the ability to test API calls. The best thing about Swagger UI is that it is quite simple to implement, with only a few steps to get you up and running.

In this blog post, we’ll walk you through the process.

Download Swagger UI

There are a few options to download and implement Swagger UI, including NPM, unpkg, and Docker. The easiest, and most commonly used method to implement Swagger UI is the “Plain old HTML/CSS/JS (Standalone)” method. This method includes all the HTML, CSS, and JS files needed to run SwaggerUI in an HTML5 output, without requiring NPM.

  1. Download the latest release from this link.
Swagger UI in MadCap Flare 1

I chose “Source code (zip)” under Assets.

  1. Copy the /dist folder, and place it in your Flare project.
    In my example, I created a “Swagger UI” folder within the Resources folder of my Flare project to house the /dist folder.
    The /dist folder will have all of the assets needed to use Swagger UI in your output.
  2. Open the “index.html” file within the dist folder, then switch to the Text Editor view of the XML Editor. On line 48, replace "https://petstore.swagger.io/v2/swagger.json" with the URL of your hosted JSON file, wrapped in double quotes.
Swagger UI in MadCap Flare 2

Add Swagger UI to your HTML5 Output

Now that we have implemented Swagger UI in our Flare project, let’s reference the index.html to include it in our output!

You have options for how you would like to reference this file. You could insert a hyperlink or cross-reference to the index.html file from one of your topics that is included in your TOC. Another option would be to create a TOC entry that links to the index.html file, so your API documentation can be selected from the navigation bar.

Swagger UI in MadCap Flare 3

Once you have referenced the index.html file, you can build your HTML5 output to see your Swagger API documentation living alongside your docs, complete with dynamic “Try it out” functionality!

Swagger UI in MadCap Flare 4
Swagger UI in MadCap Flare 5

We hope you find this tip helpful! If you have any API documentation tips you would like to share or have any questions about integrating Swagger into your HTML5 outputs, drop us a line below.