Add Docs to Product


Add Documentation

Additional Markdown documentation can also be added to improve the understanding and consumption experience of products. Markdown documents also exist as table-of-contents resources within a product section. A Markdown document reference can be added to a product via a POST Add table of contents entry request.

The difference between a Markdown document and an API Reference document is described via the content object in the request payload. The order to control where the document will appear in the table-of-contents.

A sample cURL request to add a documentation reference:

curl --location --request POST 'https://api.portal.swaggerhub.com/v1/sections/<SECTION-ID>/table-of-contents' 
--header 'Authorization: Bearer <YOUR-SWAGGERHUB-APIKEY>' \
--header 'Content-Type: application/json' \

--data '{
  "slug": "getting-started",
  "title": "Getting Started Guide",
  "order": 0,
  "content": {
    "type": "markdown"
  } 
}'

Sample response body:

{
  "id": "0afe1039-e1a4-4bb3-9d13-a0e7c2a6942c",
  "documentId": "5af87df5-ff80-4423-a0a1-a1db5fb99cb7"
}

Add Markdown contents

Now that the documentId of the table-of-contents resource for the markdown has been obtained, the content itself can be prepared. Markdown content can be added to the document via a PATCH Update the contents of a document request.

A sample cURL request to update document content:

curl --location --request PATCH 'https://api.portal.swaggerhub.com/v1/documents/<DOCUMENT-ID>' \
--header 'Authorization: Bearer <YOUR-SWAGGERHUB-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 from various locations. Whether you're building a React UI app or integrating with other platforms, this guide will help you get started quickly.\n\n## API Key\n\nTo access the API, you'll need an API key. Obtain your API key by signing up on our developer portal at [https://api.example.com](https://api.example.com). The API key will be used for authentication in API requests.\n\n## Endpoints\n\nThe API provides the following endpoints:\n\n1. `/pets`: Retrieve a list of available pets for adoption.\n2. `/pets/{id}`: Get detailed information about a specific pet by its ID.\n3. `/locations`: Retrieve a list of adoption locations.\n4. `/locations/{id}`: Get details about a specific adoption location.\n\n## Authentication\n\nInclude your API key in the `X-API-Key` header of each request for authentication.\n\n## Exploring the API\n\nTo start browsing for orphaned pets, make a `GET` request to `/pets`. This will provide a list of available pets, including their names, breeds, ages, and other relevant information.\n\nTo adopt a pet, make a `POST` request to `/pets/{id}/adopt`, where `{id}` is the ID of the pet you wish to adopt. This will initiate the adoption process and provide further instructions.\n\n## Business and Ethical Value\n\nThe Pets and Adoptions API goes beyond just facilitating pet adoption. By using this API, you contribute to the well-being of orphaned pets and support ethical adoption practices. Here's why the API is valuable:\n\n1. **Increased Pet Adoption:** By providing a user-friendly interface and seamless integration capabilities, the API enables more individuals and platforms to discover and adopt orphaned pets, increasing the chances of finding them forever homes.\n\n2. **Efficient Adoption Process:** The API streamlines the adoption process by providing comprehensive pet information, enabling users to make informed decisions. It also simplifies administrative tasks for adoption locations, allowing them to focus on caring for the pets.\n\n3. **Platform Integration:** The API's versatility allows integration with various platforms, such as mobile apps and websites, expanding the reach of the adoption services. This fosters collaboration and partnerships within the pet adoption community.\n\n4. **Promoting Ethical Adoption Practices:** The API promotes responsible pet adoption by ensuring transparency in pet information and adoption locations. It supports verification and authentication processes, safeguarding pets' well-being and avoiding fraudulent practices.\n\nBy leveraging the Pets and Adoptions API, you contribute to a positive impact on the lives of orphaned pets and the individuals who provide them with loving homes.\n\n## Documentation\n\nFor detailed API documentation and examples, please refer to our [API documentation](https://api.example.com/docs).\n\nIf you have any questions or need further assistance, don't hesitate to reach out to our support team at [support@example.com](mailto:support@example.com).\n\nHappy browsing and thank you for being part of the Pets and Adoptions community!"
}'

After adding documentation and linking an API reference, the published portal product documentation looks like follows:

Sample Portal Product Documentation
Sample Portal Product API Reference

Nest Pages

Nesting allows you to nest pages and pages only. Note that it's not possible to nest under API.

Once you have added a page in your Table of Contents, you can now add subpages to it, which will result in a nested structure of your content. There is no limit to nesting depth.

There are new parameters for the /table-of-contents/{id} endpoint, and they are described in the table below with reference to an HTTP method in which they appear:

MethodParameterDescription
GETchildrenIncludes children pages (subpages of a page).
POST, PATCHparentIdRefers to a parent page. If this value is null, it means the page is at a root level.
DELETErecursiveFlag to include all the nested tables of contents. Default: false.

To add a nested page (a subpage) to the page added above (Getting Started Guide), the POST Add table of contents entry endpoint can be leveraged, with the parentId parameter referring to the parent page or section.

A sample cURL request to update document content:

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-SWAGGERHUB-APIKEY>' \

--data '{
  "title": "New subpage",
  "parentId": "<PARENT-PAGE-ID>",
  "content": {
    "type": "markdown"
  },
  "slug": "new-subpage",
  "order": "1"
}'

Sample response body:

{
    "id": "b291a0ca-504c-4dac-a8e3-a949846baf55",
    "documentId": "d0589b79-9afc-4beb-ade8-72d5d8b31a2c"
}