API Changelog

This page contains a log of all changes to the API and the versions that are related to each new addition.

VersionRelease dateChange notes
0.1.0-beta2023-08-18view notes
0.2.0-beta2024-04-23view notes

v0.2.0-beta (latest)

🚧This version is classified as being in beta and is subject to breaking changes over the coming period. That being said, we do encourage consumption and experimentation of the API.

  • Updated securitySchemes documentation to reflect the required permissions for each endpoint with granular access.
  • Breaking change: only organization owners can delete products (previously designers could too).
  • slug is no longer required when creating a table of contents entry. If it is not specified, it will be generated automatically from the title.
  • The latest public API definition is exposed at /v1/openapi.json and /v1/openapi.yaml.
  • When creating or updating a Portal, the openapiRenderer field can be set to toggle the setting for Elements or Swagger UI.
  • The GET Get unpublished changes returns more information in the modified list about what changed.
  • The GET Get unpublished changes now returns a "missing" list, to indicate that SwaggerHub APIs could not be fetched because the URL is no longer valid or the user does not have enough permissions.
  • The PUT Publish content changes endpoint returns validation errors in the case that an API can't be retrieved from SwaggerHub, or can't be resolved.
  • A couple of endpoints have been renamed for consistency (the old endpoints are still in place but may be removed in the future):

v0.1.0-beta

Initial launch of the SwaggerHub Portal API.

🚧This version is classified as being in beta and is subject to breaking changes over the coming period. That being said, we do encourage consumption and experimentation of the API.

The API provides the ability to access, manage, and update the following resources:

ResourceDescription
PortalsA collection representing portal instances and allowing management on portal instances settings. The portal settings control the branding, name, domain url, and availability of a portal. These settings are split into three levels: general, branding, and landingPage.
ProductsA collection of metadata (a.k.a. product settings), API reference documents (for example, an OpenAPI document), and Markdown documents which are bundled and presented to a consumer as a product.
DocumentsA resource for storing document content (specifically for Markdown files).
SectionsA section is a resource used to hold API references as well as API document references and organize them into tables of contents.