How to Include Rich Content in Your API Documentation

Clear documentation is a vital part of any API that you publish for broad consumption. No matter the quality of the API itself, consumers need documentation to get the most out of the API with a minimum amount of friction. A comprehensive specification is a great starting point, but often more is needed to establish context, use cases, complex examples, and visual aids. 

Your REST API documentation can include rich content, such as searchable and indexed rich text, embedded images, tables, and media files. You can include this rich content using CommonMark markdown, upload this file to your API in your portal, and then view how the portal renders this content within your API on the Spec tab.

This short video illustrates how to include rich content in your API documentation, how to upload this Swagger file to your API in API Portal, and then how API Portal renders this content, using Layer7 as the example.