Note: This post follows on from two previous posts on creating a unified API documentation portal:
We’ve just uploaded an example project of an API documentation portal created using MadCap Flare:
- API documentation portal home page
- Swagger Petstore – test 1
- Swagger Petstore – test 2
- Stripe-style API documentation
- API PDF manual
The documentation portal includes API reference documentation that was generated automatically from a Swagger/OpenAPI specification file.
Whenever the REST API specification is updated, that content automatically updates itself in the Flare project.
Using MadCap Flare means you can provide a consistent user experience: for the reference, troubleshooting, getting started and tutorial content. Flare also manage the content, search, linking, pdfs, tables, flowcharts etc.
The steps are:
- Generate the API reference documentation in HTML format from the OpenAPI specification file. This could be generated automatically each day.
- Import the API reference HTML file into Flare. Select Link Generated Files to Source Files. This creates a connection between the original HTML files and the files that are created as a result of the import. Flare recognises when changes have been made to the source documents.
- Fix any initial CSS issues. The API reference HTML file links to a cascading stylesheet file. We found we needed to create a CSS file with the same name, as there were some issues with displaying the top navigation menu bar.
- Generate and publish your web site. You can run Flare’s “Build” command from the operating system’s command line. This means you can create a batch file with the necessary commands in it. Then you can use a scheduling tool to run the batch file automatically.
Further work could be done to improve the outputs:
- We’ve not made any changes to the default styles for the PDF manual.
- Amending the cascading stylesheet for the Stripe-style API documentation
- Adding code samples.