Overview

API documentation facilitates the use, integration, and basic understanding of your API and is an essential guide or manual for developers/users of your APIs. Good documentation can include various content such as code examples, tutorials, usage scenarios, and much more. Ultimately, good documentation is an important part of a positive Developer Experience (DX) as it enables users to solve problems on their own and can lead to increased API usage and adoption.

To make the documentation of your APIs as simple and comprehensive as possible, the API Control Plane gives you the freedom and flexibility to structure and design it as you wish. You can work with pages based on Markdown or Rich Text and create a folder structure according to your wishes. You can also create a folder, link it to Git, and obtain your documentation from there.

If you navigate to the Documentation menu item in the second navigation menu within an API, you will see the first level of the documentation listed in tabular form.

In the top right-hand corner, there is a button that you can use to create a new item in the documentation (more on this below).

There can be different types of documentation items:

• Markdown: Creates a new page in the documentation of the type "Markdown", which can be created and edited using a special Markdown editor. Markdown is an easy-to-use markup language that allows you to add formatting elements ( e.g. headings, links, or lists) to plain text.

• Rich Text: Creates a new page in the documentation of the type "Rich Text". Rich text allows for more sophisticated formatting and styling with an editor that is comparable to a WYSIWYG editor.

• Folder: Creates a new folder, that can contain all types of documentation pages or other folders.

The table itself is divided into three columns:

• The Type of the documentation item, which is indicated through an icon:

  • : Markdown

  • : Rich Text

  • : Folder

• The Name of the documentation item, which must be unique.

• The Status of the documentation item, which specifies whether this documentation page is displayed in the developer portal ("published") or not ("not published").

By clicking on the individual entries in the table, you can access the respective documentation item to edit it or change its settings.

If the selected documentation item in the table is of the type "Folder", you will be transferred one hierarchy level down into the folder. There you have two more menu items to choose from:

• Content: Here you will see the same table as described above for the first hierarchy level (Overview).

• Settings: Here you can adjust various settings for this folder (more on this below).

In the top right-hand corner, there is a drop-down menu that you can access using the three dots. There you can delete the current folder if it contains no more items and create new documentation items.

If the selected documentation item in the table is of the types "Markdown" or "Rich Text", you will be transferred to an edit page of the corresponding type. here you have two more menu items to choose from:

• Content: Depending on the type of page, a separate editor is displayed here. Details on this are described below in the sections "Edit a Markdown Page" or "Edit a Rich Text Page".

• Settings: Here you can adjust various settings for this page (more on this below).

The current page can be deleted using the "Delete Item" button in the top right-hand corner.

To navigate back by one hierarchy level, you can click on the three dots to the left of the icon and the name of the current item.

Create a New Documentation Item

To create a new documentation item, select the "Create New Item" button in the top right-hand corner or the corresponding menu item from the drop-down menu in the same location.

This will open a new dialog window in which you have various input fields and other settings:

• Name: With this input field, the documentation item can be given a name, which must be unique in the documentation of this specific API.

• Type of the Item: Here you can choose between three types of items as listed below.

  • Markdown: Creates a new page in the documentation of the type "Markdown", which can be created and edited using a special Markdown editor. Markdown is an easy-to-use markup language that allows you to add formatting elements ( e.g. headings, links, or lists) to plain text.

  • Rich Text: Creates a new page in the documentation of the type "Rich Text". Rich text allows for more sophisticated formatting and styling with an editor that is comparable to a WYSIWYG editor.

  • Folder: Creates a new folder, that can contain all types of documentation pages or other folders.

• Toggle “Welcome Page of this API”: This option specifies which documentation page should be displayed as the overview page in the developer portal for the corresponding API. Only one documentation can be selected as a welcome page at a time. The last setting overwrites the previous one. This toggle is only visible for documentation items of the types "Markdown" and "Rich Text".

To create the documentation item with the settings you have specified, click on the "Create New Item" button.

Edit a Markdown Page

If you edit an item of the type 'Markdown', a special markdown editor is displayed. This editor is divided into two parts. On the left side you can make your entries and use the special control characters for markdown. On the right side you will see an updated and rendered version of your input. All formatting options using Markdown can be found in the official documentation.

You can use the toggle 'Auto Save' to set whether the entries you make on the left should be saved permanently or not. If you deactivate this option, you will have to click on the save button at the bottom of your edit to save your changes permanently.

You can call up the image management dialog via the 'Image Management' button.

Here you can upload any kind of image. It will be saved until you delete it. Everyone who has access to this API can also see the uploaded image. The maximum size is 2 MB.

Select the image you want to display in the documentation, copy the Markdown snippet that appears below and paste it into your documentation.

Edit a Rich Text Page

With the type rich text you get a graphical editor with which you can easily and conveniently create documentation. You can also use this type to create your documentation in HTML.

A summary of all HTML templates can be found here: CMS Template Library

If you want to edit an item of the 'Rich Text' type, you first come to the read only editor. here you can view the current item in its current state. To edit the item, click on the 'Edit' button. The editor then switches to edit mode. In this mode you have many different tools at your disposal, which are known from standard text editing programs. You can edit texts directly in the editor.

To insert our predefined HTML templates, you can click on the 'Insert Template' button or on the stamp symbol . This will open another window with all available templates.
If you want to edit the plain HTML you have to click on the source code symbol . This will open another window which displays the complete item as HTML code. Here you can insert new HTML code or edit existing code.

To save your changes, click on the 'Save' button.

Change the Settings of a Page or Folder

Items of the type 'Markdown' or 'Rich Text' have the same structure as the settings view. The item of type 'Markdown' differs from the other types in the settings view only in that it has no toggle 'Welcome Page of this API'. There are various input fields and toggles in the settings view.

• Name: Specifies the name of the item, which must be unique.

• Toggle 'Published': Use this option to specify if this documentation page should be displayed in the developer portal.

• Toggle 'Welcome Page of this API': Use this option to specify which documentation page should be displayed as the overview page in the developer portal for the corresponding API. Only one documentation can be selected as a welcome page at a time. The last setting overwrites the previous one.

• Url: The url to the Git repository.

• Git Credential: The Git credential to log in to the Git repository. The Git credentials can be created in Configuration > Git Credentials.

• Branch: The branch within the Git repository.

• Path: The path within the Git repository.

• Fetch interval: The interval at which the latest version should be checked.