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?”
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.
- Download the latest release from this link.
I chose “Source code (zip)” under Assets.
- 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.
- 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.
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.
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!
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.