Create Get started guides for your API Products

Introduction and motivation

As an API Provider, you can package APIs into API Products and supply them with documentation to deliver value to your internal and external API Consumers.
API documentation is essential for API Products. Good API documentation goes beyond just Open API Specification. To make your API Products easy to use and engaging, you can add technical and business guides to the documentation of your API Products, for instance:

• Get started guides explaining how to start with your API Product;
• Use-cases;
• Business documentation that explains the business value and helps to convince decision-makers.

Tyk Enterprise Developer portal provides two ways of documenting APIs:

• Open API Specifications for APIs;
• The Get started documentation feature enables API Providers to add as many technical and business guides to API Products as needed.

This guide explains how to add the Get started documentation to API Products.

Step 1: Create and publish an API Product

To start with, create and publish an API Product. Please refer to the Publish API Products and Plans page for further guidance.

Step 2: Add API Documentation to API Products

To add API Documentation, select an API Product and navigate to the API Documentation section. Click the ‘Add API Documentation’ button to add a new API Documentation page.

Tyk developer portal stores two versions of each API Documentation page: in Markdown and HTML formats. You can edit both versions, but only one version of the page will be displayed. To edit the Markdown version, click on the ‘Change to Markdown’ button.

To edit the HTML version, click the ‘Change to HTML’ button.

To select which version of the documentation to display, check the ‘Display Markdown’ checkbox. When it’s checked, the portal will display the Markdown version of the page. Otherwise, portal will display the HTML version.

Step 3: Add more documentation pages and set the display order

With the Tyk developer portal, you can add multiple Markdown and HTML pages to your API Products and select their display order to form a table of contents suitable for your use case. Please refer to the previous step to add one more documentation page to the API Product.

To reorder API Documentation items, scroll down to the API Documentation section and click on the ‘Reorder items’ button.

Then click on the ‘Move up’ button to move an API Documentation item one position up, and the ‘Move down’ button to bring it one position down. Click on the ‘Done’ button and then on the ‘Save’ button to save your changes.

Once you save the changes, the new order of items will be reflected in the ‘Get started’ tab.

All documentation pages are listed in the ‘Product docs’ section. You can access and edit the API docs from that section.

Step 4: Add tags to blogs and API Products

Finally, you can add blog posts to your API Products using the Tags feature. You can specify tags for API Product and blog posts, then the blog posts that match tags with an API Product will be displayed in the ‘Related blog content’ section.

To specify tags for an API Product, select an API Product, scroll down to the ‘Tags’ section, type in a tag, and press the Enter key.

To specify tags for a blog post, select a blog post, scroll down to the ‘Tags’ section, type in a tag, and press the Enter key.

The blog posts that match tags with an API Product will be displayed in the ‘Related blog content’ section of the respective API Product page.