Additional documentation (Markdown or HTML) can be added to enhance the user’s understanding and experience of API products. These documents are added as table-of-contents entries.
Use the POST Add table of contents entry endpoint to link a Markdown document.
📌 The
contenttypemarkdown/htmldistinguishes documentation from API references.
Sample Request
curl --location --request POST 'https://api.portal.swaggerhub.com/v1/sections/<SECTION-ID>/table-of-contents' \
--header 'Authorization: Bearer <YOUR-SWAGGER-APIKEY>' \
--header 'Content-Type: application/json' \
--data '{
"type": "new",
"slug": "getting-started",
"title": "Getting Started Guide",
"order": 0,
"content": {
"type": "markdown",
"source": "external"
}
}'🚧 Important: The
sourcepropertyinternal/externaldetermines if it's possible to edit document's content only via API (external) or in the UI (internal). The default value isinternal.For documents managed via API flows you can prevent edits in the UI by setting
sourcetoexternal
Sample Response
{
"id": "0afe1039-e1a4-4bb3-9d13-a0e7c2a6942c",
"documentId": "5af87df5-ff80-4423-a0a1-a1db5fb99cb7"
}Add Contents
Use the PATCH Update the contents of a document endpoint to provide actual content.
curl --location --request PATCH 'https://api.portal.swaggerhub.com/v1/documents/<DOCUMENT-ID>' \
--header 'Authorization: Bearer <YOUR-SWAGGER-APIKEY>' \
--header 'Content-Type: application/json' \
--data '{
"content": "# Getting Started with the Pets and Adoptions API\n\nWelcome to the Pets and Adoptions API! This API empowers you to browse and adopt orphaned pets..."
}'After documentation and API reference are added, the portal may look like:
Nest Pages
Nesting allows you to nest pages for better content structure. Use the parentId field in the request payload to create subpages.
The following parameters are used with the /table-of-contents/{tableOfContentsId} endpoint:
| Method | Parameter | Description |
|---|---|---|
| PATCH | parentId | Indicates parent page. If null, page is root-level. |
| PATCH | order (nullable) | The order of the item in the table of contents, starting from 0. If explicitly set to null, the item will be moved to the end of the list. |
| PATCH | slug | The URL slug. |
| PATCH | title | The title of the table of contents. |
| DELETE | recursive | Deletes nested subpages if set to true. |
Sample Request to Add Subpage
curl --location --request POST 'https://api.portal.swaggerhub.com/v1/sections/<SECTION-ID>/table-of-contents' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR-SWAGGER-APIKEY>' \
--data '{
"type": "new",
"title": "New subpage",
"parentId": "<PARENT-PAGE-ID>",
"content": {
"type": "markdown",
"source": "external"
},
"slug": "new-subpage",
"order": "1"
}'Sample Response
{
"id": "b291a0ca-504c-4dac-a8e3-a949846baf55",
"documentId": "d0589b79-9afc-4beb-ade8-72d5d8b31a2c"
}