Example of API documentation portal using MadCap Flare

This post follows on from our Creating an API documentation portal with MadCap Flare and Swagger/OpenAPI post. It shows screenshots of a test project we created. We used Swagger’s “petstore” example API specification as the source content. We didn’t spend any time modifying the stylesheets – these are just proofs of concept.

API documentation Home page

All the content uses the same navigation, and look and feel:

API documentation example in MadCap Flare - Home page

API reference information – single page

In this example, all the reference information is stored in a single file. We set the Flare project up in a way that this content updates automatically whenever the API specification file changes. There’s more work required on the stylesheet and Flare master pages in order to improve the look and feel.

API documentation example in MadCap Flare - Single reference page

API reference information – multiple pages

In this example, all the reference information is split into a multiple files. We set the Flare project up in a way that this content updates automatically whenever the API specification file changes. There’s more work required on the stylesheet and Flare master pages in order to improve the look and feel.

API documentation example in MadCap Flare - split into multiple pages

API reference information – resources and endpoints

API documentation example in MadCap Flare - post example

API documentation example in MadCap Flare - resource example

Incorporating content created by developers in Markdown

This shows an example of content created by a developer in Markdown format and imported into the project. This means the developers wouldn’t have to use Flare for any of their contributions, if they didn’t want to.

API documentation example in MadCap Flare - Markdown import

The advantage of this approach is it would give users a coherent and consistent user experience across all the API documentation.

See also: Cherryleaf’s API documentation writing services.

Leave a Reply