SmartBear

Once a product has been created, it can be hydrated with the technical API reference documents (for example, an OpenAPI document or AsyncAPI document) and additional Markdown documents to further explain to consumers how to get up and running with the product.

The SwaggerHub Portal APIs can be leveraged to automate the creation of API references and additional documentation material which can enhance the developer experience (DX) of published products.

The following API resources and paths are leveraged:

/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 creating a product a default section is created which is accessible via a GET Retrieve a specific section. request.

Sample cURL request:

curl --location 'https://api.portal.swaggerhub.com/v1/sections?productId=<PRODUCT-ID>' \
--header 'Authorization: Bearer <YOUR-SWAGGERHUB-APIKEY>'

Sample response payload:

{
  "items": [
    {
      "id": "02fdcafc-9328-4eb2-8315-a2ce34d9644b",
      "productId": "afda3749-2314-4153-a53f-ed54ab2387b2",
      "title": "default",
      "slug": "default"
    }
  ]
}

note keep note of the returned id for the section, as it will be needed for later API calls to add API references and documentation.

Add API Reference

API reference documents (for example, an OpenAPI definition) exist as table-of-contents resources within a product section. An API reference document can be added to a product via a POST Add table of contents entry.

Note that currently only SwaggerHub hosted API references can be linked to portal products. Please have the published URL of your SwaggerHub API ready when preparing the API request below!

A sample cURL request to add an API 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": "pets-and-adoptions-api-1.0.0",
  "title": "Pets and Adoptions API",
  "order": 1,
  "content": {
    "type": "apiUrl",
    "url": "https://api.swaggerhub.com/apis/frank-kilcommins/Pets-and-Adoptions-API/1.0.0/swagger.json"
  } 
}'

Sample response body:

{
  "id": "4adfa584-c88f-49a8-b66e-7e90f3c20395"
}

Note that it's not possible to nest under an API. Although, you can nest pages.