Swagger Portal Integration

The Swagger Portal client provides comprehensive portal and product management capabilities. Access to these features requires authentication with a SWAGGER_API_KEY.

Available Tools

Portal Management Tools

list_portals

• Purpose: Search for available portals within Swagger. Returns only the portals for which you are an owner or designer, either at the product or organization level.
• Returns: Paginated list of portals, including metadata such as name, subdomain, status, and more.
• Use case: Discovery of available portals.

get_portal

• Purpose: Retrieve information about a specific portal.
• Parameters: Portal UUID or subdomain (portalId).
• Returns: Complete set of metadata properties for a specific portal.
• Use case: Get full details on a specific portal configuration.

create_portal

• Purpose: Create a new portal with Swagger.
• Returns: Complete set of metadata properties for a specific portal.
• Use case: Get full details on a specific portal configuration.
• Parameters:

update_portal

• Purpose: Update a specific portal's configuration.
• Returns: Complete set of metadata properties for a specific portal.
• Use case: Update configuration settings of existing Swagger portal.
• Parameters:

list_portal_products

• Purpose: Get products for a specific portal.
• Parameters: Portal UUID or subdomain (portalId).
• Returns: Paginated list of products in a portal.
• Use case: Understanding the products that exist for a given portal.

get_portal_product

• Purpose: Retrieve information about a specific product resource.
• Parameters: Product UUID (productId).
• Returns: Complete set of properties for a specific product.
• Use case: Understanding the product information and status (both from a publishing and visibility perspective).

create_portal_product

• Purpose: Create a new product within a specific portal.
• Returns: Information about the newly created product.
• Use case: Add a new product to a portal.
• Parameters:

update_portal_product

• Purpose: Update an product within a specific portal.
• Returns: Information about the update product.
• Use case: Change information on an existing product.
• Parameters:

delete_portal_product

• Purpose: Delete a product from a specific portal.
• Parameters: Product UUID (productId).
• Returns: No content on success.
• Use case: Delete an existing product from a Swagger portal.

publish_portal_product

• Purpose: Publish a product's content to make it live or as preview. This endpoint publishes the current content of a product, making it visible to portal visitors. Use preview mode to test before going live.
• Returns: Publication status information.
• Use case: Make product content visible to portal visitors, either as live content or preview for testing.
• Parameters:

Product Sections Management

list_portal_product_sections

• Purpose: Get sections for a specific product within a portal.
• Returns: List of sections within a product, including metadata and embedded table of contents if requested.
• Use case: Understanding the structure and organization of content within a product.
• Parameters:

Table of Contents Management

create_table_of_contents

• Purpose: Create a new table of contents item in a portal product section. Supports API references, HTML content, and Markdown content types.
• Returns: Information about the newly created table of contents item.
• Use case: Add structured content navigation to product sections.
• Parameters:

list_table_of_contents

• Purpose: Get table of contents for a section of a product within a portal.
• Returns: List of table of contents items within a section, including nested structure and content metadata.
• Use case: Understanding the navigation structure and content organization within a product section.
• Parameters:

delete_table_of_contents

• Purpose: Delete table of contents entry. Performs a soft-delete of an entry from the table of contents. Supports recursive deletion of nested items.
• Returns: No content on success.
• Use case: Remove table of contents items and optionally their nested structure.
• Parameters:

Document Management

Note: Documents are managed as part of table of contents items. To delete a document, use delete_table_of_contents which will remove the table of contents entry and any associated document content.

get_document

• Purpose: Get document content and metadata by document ID. Useful for retrieving HTML or Markdown content from table of contents items.
• Returns: Document content and metadata including type, creation/modification dates.
• Use case: Retrieve content for editing or display purposes.
• Parameters:

update_document

• Purpose: Update the content of an existing document. Supports both HTML and Markdown content types.
• Returns: Updated document metadata.
• Use case: Modify existing documentation content within portal products.
• Parameters:

Configuration

To use Swagger Portal tools, you need to configure the SWAGGER_API_KEY environment variable with your Swagger API token.

Common Use Cases

1. Portal Discovery: Use list_portals to find available portals you have access to.
2. Portal Management: Create and update portals using the respective tools.
3. Product Organization: Manage products within portals for better API organization.
4. Content Publishing: Use publish_portal_product to make product content live or preview changes before publishing.
5. Content Structure Management: Organize product content using sections and table of contents for better navigation.
6. Document Management: Create, update, and manage documentation content within portal products.
7. Portal Content Architecture: Build comprehensive documentation portals with nested content structures and API references.