Add APIs to Product
Once a product has been created, it can be hydrated with technical API reference documents (for example, an OpenAPI or AsyncAPI document) and additional documentation (Markdown or HTML) to help consumers understand how to get started with the product.
The SwaggerHub Portal APIs can be leveraged to automate the creation of API references and supplemental documentation to enhance the developer experience (DX) of published products.
The following API resources and paths are used:
/sections/sections/{sectionId}/table-of-contents/attachments/documentation/{portalId}/documents/{documentId}
Within the portal, API reference material and documentation are grouped under a resource known as sections. When a product is created, a docs section is also created, which is accessible via a GET Retrieve a specific section request.
Retrieve Section – Sample Request
Sample Response Payload
📝 Note: Keep note of the returned
idfor the section, as it will be needed in subsequent API calls.
Add API Reference
API reference documents (e.g., OpenAPI definitions) exist as table-of-contents resources within a product section. An API reference can be added using the POST Add table of contents entry endpoint.
📌 Note: Currently, only SwaggerHub-hosted API references can be linked to portal products. Have the published URL of your SwaggerHub API ready.
Sample Request to Add an API Reference
Sample Response Body
❗ Note: It is not possible to nest content under an API reference, but you can nest pages under each other.