Preview and Publish Content | Portal APIs

Initially, all added documents and APIs are visible only on the designer side of the Portal. To make them accessible to your consumers, an additional action is required.

💡 Resolved State
The APIs linked in products are in an unresolved state. The API is in a resolved state after a Preview or Publish action. A resolved state means that the APIs also show:
Contents of external references, if there are external references in the API.
Domains information, if domains are referenced in the API in SwaggerHub.

Get unpublished changes

Before publishing the content, it is advisable to review the changes that will be visible to consumers. To accomplish this, use the GET Unpublished changes endpoint. The response will provide a list of all entries that have been added since the product's creation or modified since the last publication, as well as existing comments and suggestions that will be omitted in the publishing process if not accepted before.

Sample Request

Sample Response

🚧 Important: You cannot publish if any of your APIs are un-resolvable or are missing.
Possible causes if any of your APIs are un-resolvable:
Provider doesn't have correct permissions to access external references
API validation issues related to references
If any of your APIs appears as missing, it means it is inaccessible in Swagger Studio and must be unlinked to preview or publish the product. Possible causes:
API renamed in Swagger Studio
API deleted from Swagger Studio
Provider doesn't have correct permissions to the API
Anything that affects the API URL structure

Publish content

Use the PUT Publish product endpoint to publish changes made to the product.

Sample Request

In case of a processing error, the response with validation message is returned providing information of the error type and ID of each table-of-contents entry that caused the issue.

Sample Response

Possible error types and their explanation:

Error Code	Detail
NOT_FOUND	The requested resource was not found.
AUTH_FAILURE	Access token not set or invalid. The requested resource could not be returned.
INVALID_URL	Syntax of URL is invalid.
URL_NOT_ALLOWED	URL is not allowed for security reasons.
INVALID_API	API is not a valid OpenAPI, AsyncAPI or GraphQL.
YAML_JSON_INVALID	Invalid YAML or JSON format.
PARSE_ERROR	Error while parsing (Swagger/OpenAPI parser message).
CANT_PROCESS_SCHEMA	Error while processing GraphQL schema.
UNKNOWN	All other errors.

Preview product

To preview the content of a specific product before actually publishing, you can use PUT Publish product endpoint with preview query parameter value set to true.

Sample Request

Then use GET Published sections endpoint to check which table-of-contents entries were affected and GET Published page to review content that would be published under the specific path. Both endpoints require preview=true parameter to return data of generated preview. If the value is not specified, endpoints will return last published content by default.

Get Published Sections

Sample Request

Sample Response

Get Published Page

Sample Request

📝 Note: path parameter value is required. You can copy its value from GET Published section response or combine section's and table-of-contents' slugs