fix: customdomain and other refactors

Author: VarshaNagtilak1

CHANGELOG.md

@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- [Swagger] Refactored `publish_portal_product` to build published URLs dynamically from `SWAGGER_PORTAL_BASE_PATH`, support preview and section/table-of-contents paths, and return the resolved `liveUrl` or `previewUrl` in the publish response.
+- [Swagger] Refactored `publish_portal_product` to build published URLs dynamically from `SWAGGER_PORTAL_BASE_PATH`, support preview and section/table-of-contents paths, and return the resolved `liveUrl` or `previewUrl` plus product, portal, and table-of-contents metadata in the publish response. If `portal.customDomain` is present, the client now uses it as the full host without appending the portal UI suffix.
 
 ### Added
 

docs/products/SmartBear MCP Server/swagger-portal-integration.md

@@ -116,7 +116,14 @@ The Swagger Portal client provides comprehensive portal and product management c
 #### `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, including the generated `liveUrl` for live publication or `previewUrl` for preview publication when the product can be resolved.
+- Returns: Publication status information with the following structure:
+  - `success` (boolean): Publication success status
+  - `preview` (boolean): Whether this is a preview or live publication
+  - `liveUrl` (string, conditional): Generated live URL (only when preview is false)
+  - `previewUrl` (string, conditional): Generated preview URL (only when preview is true)
+  - `product` (object): Product metadata with fields: `id`, `name`, `slug`
+  - `portal` (object): Portal metadata with fields: `id`, `name`, `subdomain`, `customDomain`
+  - `tableOfContentsItem` (object | null): Table of contents metadata with fields: `id`, `slug`, `title`, `order`, `parentId` (null when tableOfContentsId is not provided or not found)
 - Use case: Make product content visible to portal visitors, either as live content or preview for testing.
 - Parameters:
 
@@ -126,7 +133,11 @@ The Swagger Portal client provides comprehensive portal and product management c
 | `preview`   | Whether to publish as preview (true) or live (false). Preview allows testing before going live. Defaults to false (live publication) | boolean | No       |
 | `tableOfContentsId` | Optional table of contents UUID, or identifier in the format 'portal-subdomain:product-slug:section-slug:table-of-contents-slug' used to resolve a specific live URL path | string | No |
 
-The publish response now includes `liveUrl` for live publication and `previewUrl` for preview publication. The URL is built dynamically from the configured `portalBasePath`, so it works across dev2, int, and production environments. When `tableOfContentsId` resolves, the returned URL includes the section and table-of-contents path.
+**Response Details:**
+- When `portal.customDomain` is present, it is used as the full host in the generated URL without appending the portal UI suffix
+- When `customDomain` is not present, the URL is built using `portal.subdomain` + the portal UI suffix (`.portal.swaggerhub.com`)  
+- When `tableOfContentsId` resolves successfully, the returned URL includes the section and table-of-contents path in the format: `/{productSlug}/{sectionSlug}/{tocSlug}`
+- The response includes only essential fields from product, portal, and tableOfContentsItem following React/TypeScript best practices using Pick<> utility types
 
 ### Product Sections Management
 

src/swagger/client/api.ts

@@ -381,15 +381,12 @@ export class SwaggerAPI {
       }),
     ]);
 
-    // Fetch portal details after portalId ID is available
     const portalDetails = await this.getPortal(
       String(productDetails.portalId ?? ""),
     );
 
-    // Get the first section (primary section)
     const targetSection = sections.items[0] ?? null;
 
-    // Resolve the target table of contents item if tableOfContentsId is provided
     const targetTocItem =
       tableOfContentsId && targetSection
         ? findTableOfContentsItem(
@@ -398,18 +395,15 @@ export class SwaggerAPI {
           )
         : null;
 
-    // Build live URL using environment-specific domain
-    const host = portalDetails.customDomain ?? portalDetails.subdomain;
     const publicationUrl = buildPortalLiveUrl(
       this.config,
-      host,
+      portalDetails,
       productDetails.slug,
       targetSection,
       targetTocItem,
       preview,
     );
 
-    // Publish the product to the portal
     const response = await fetch(
       `${this.config.portalBasePath}/products/${productId}/published-content?preview=${preview}`,
       {
@@ -424,9 +418,28 @@ export class SwaggerAPI {
 
     return {
       ...result,
+      preview,
       ...(preview
         ? { previewUrl: publicationUrl }
         : { liveUrl: publicationUrl }),
+      product: {
+        id: productDetails.id,
+        name: productDetails.name,
+        slug: productDetails.slug,
+      },
+      portal: {
+        id: portalDetails.id,
+        name: portalDetails.name,
+        subdomain: portalDetails.subdomain,
+        customDomain: portalDetails.customDomain,
+      },
+      tableOfContentsItem: targetTocItem ? {
+        id: targetTocItem.id,
+        slug: targetTocItem.slug,
+        title: targetTocItem.title,
+        order: targetTocItem.order,
+        parentId: targetTocItem.parentId,
+      } : null,
     } as PublishPortalProductResponse;
   }
 

src/swagger/client/portal-types.ts

@@ -39,7 +39,7 @@ export const GetProductSectionsArgsSchema = z.object({
     .number()
     .optional()
     .describe(
-      "Number of items per page for pagination - controls how many results are returned per page (default is 20)",
+      "Number of items per page for pagination - controls how many results are returned per page (default is 10)",
     ),
 });
 
@@ -339,7 +339,7 @@ export const PublishProductArgsSchema = ProductArgsSchema.extend({
     .string()
     .optional()
     .describe(
-      "The table of contents UUID, or identifier in the format 'portal-subdomain:product-slug:section-slug:table-of-contents-slug'",
+      "Optional table of contents UUID, or identifier in the format 'portal-subdomain:product-slug:section-slug:table-of-contents-slug'. When provided, publishPortalProduct uses it to resolve the published URL path for the returned preview/live link.",
     ),
   preview: z
     .boolean()
@@ -431,8 +431,12 @@ export type CreateTableOfContentsBody = Omit<
 export type UpdateDocumentBody = Omit<UpdateDocumentArgs, "documentId">;
 
 export type PublishPortalProductResponse = SuccessResponse & {
+  preview: boolean;
   liveUrl?: string;
   previewUrl?: string;
+  product?: Pick<Product, "id" | "name" | "slug">;
+  portal?: Pick<Portal, "id" | "name" | "subdomain" | "customDomain">;
+  tableOfContentsItem?: Pick<TableOfContentsItem, "id" | "slug" | "title" | "order" | "parentId"> | null;
 };
 
 // Response types for better type safety

src/swagger/client/tools.ts

@@ -107,7 +107,7 @@ export const TOOLS: SwaggerToolParams[] = [
     title: "Publish Portal Product",
     toolset: "Products",
     summary:
-      "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.",
+      "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. Optionally provide tableOfContentsId to form liveUrl or previewUrl for specific table-of-contents item or specific page url. Returns a PublishPortalProductResponse containing: success status, preview boolean, liveUrl or previewUrl (depending on preview mode), and narrowed metadata objects for product (id, name, slug), portal (id, name, subdomain, customDomain), and tableOfContentsItem (id, slug, title, order, parentId) when resolved.",
     inputSchema: PublishProductArgsSchema,
     handler: "publishPortalProduct",
   },

src/swagger/client/utils.ts

@@ -3,6 +3,10 @@ import type { SwaggerConfiguration } from "./configuration";
 import type { TableOfContentsItem } from "./portal-types";
 
 type UrlSegmentSource = { slug?: string } | null;
+type PortalHostSource = {
+  customDomain?: string | null;
+  subdomain?: string | null;
+} | null;
 
 /**
  * Recursively search for a table of contents item by ID.
@@ -30,17 +34,19 @@ export function findTableOfContentsItem(
  */
 export function buildPortalLiveUrl(
   config: SwaggerConfiguration,
-  host: string | undefined,
+  portal: PortalHostSource,
   productSlug: string | undefined,
   section: UrlSegmentSource,
   tocItem: UrlSegmentSource,
   preview: boolean = false,
 ): string {
+  const host = portal?.customDomain ?? portal?.subdomain;
+  const portalUiDomain = portal?.customDomain ? "" : config.getPortalUiDomainSuffix();
+
   if (!host || !productSlug) {
     return "";
   }
 
-  const portalUiDomain = config.getPortalUiDomainSuffix();
   const baseUrl = `https://${host}${portalUiDomain}/${productSlug}`;
   const previewSuffix = preview ? "?preview=product" : "";
 

src/tests/unit/common/__snapshots__/server-definitions.test.ts.snap

@@ -10440,7 +10440,7 @@ None",
 - productId (string) *required*: Product UUID or identifier in the format 'portal-subdomain:product-slug' - unique identifier for the product
 - embed (array): List of related entities to embed in the response - e.g., ['tableOfContents', 'tableOfContents.swaggerhubApi'] to include table of contents and SwaggerHub API details
 - page (number): Page number for paginated results - specifies which page of results to retrieve (default is 1)
-- size (number): Number of items per page for pagination - controls how many results are returned per page (default is 20)",
+- size (number): Number of items per page for pagination - controls how many results are returned per page (default is 10)",
     "inputSchema": [
       "embed",
       "page",
@@ -10519,16 +10519,18 @@ None",
       "readOnlyHint": true,
       "title": "Swagger: Publish Portal Product",
     },
-    "description": "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.
+    "description": "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. Optionally provide tableOfContentsId to form liveUrl or previewUrl for specific table-of-contents item or specific page url. Returns a PublishPortalProductResponse containing: success status, preview boolean, liveUrl or previewUrl (depending on preview mode), and narrowed metadata objects for product (id, name, slug), portal (id, name, subdomain, customDomain), and tableOfContentsItem (id, slug, title, order, parentId) when resolved.
 
 **Toolset:** Products
 
 **Parameters:**
 - productId (string) *required*: Product UUID or identifier in the format 'portal-subdomain:product-slug' - unique identifier for the product
+- tableOfContentsId (string): Optional table of contents UUID, or identifier in the format 'portal-subdomain:product-slug:section-slug:table-of-contents-slug'. When provided, publishPortalProduct uses it to resolve the published URL path for the returned preview/live link.
 - preview (boolean): Whether to publish as preview (true) or live (false). Preview allows testing before going live. Defaults to false (live publication) (default: false)",
     "inputSchema": [
       "preview",
       "productId",
+      "tableOfContentsId",
     ],
     "outputSchema": undefined,
     "title": "Swagger: Publish Portal Product",

src/tests/unit/swagger/api.test.ts

@@ -267,6 +267,12 @@ describe("SwaggerAPI", () => {
       subdomain: "testportal",
     };
 
+    const customDomainPortalResponse = {
+      id: portalId,
+      name: "Test Portal",
+      customDomain: "testCustomDomain.portal-testing.com",
+    };
+
     const sectionsResponse = {
       page: {
         number: 0,
@@ -353,8 +359,27 @@ describe("SwaggerAPI", () => {
 
       expect(result).toEqual({
         success: true,
+        preview: false,
         liveUrl:
           `https://testportal.portal.swaggerhub.com/${productSlug}/docs/getting-started`,
+        product: {
+          id: productResponse.id,
+          name: productResponse.name,
+          slug: productResponse.slug,
+        },
+        portal: {
+          id: portalResponse.id,
+          name: portalResponse.name,
+          subdomain: portalResponse.subdomain,
+          customDomain: undefined,
+        },
+        tableOfContentsItem: {
+          id: sectionsResponse.items[0].tableOfContents[0].id,
+          slug: sectionsResponse.items[0].tableOfContents[0].slug,
+          title: sectionsResponse.items[0].tableOfContents[0].title,
+          order: sectionsResponse.items[0].tableOfContents[0].order,
+          parentId: sectionsResponse.items[0].tableOfContents[0].parentId,
+        },
       });
     });
 
@@ -378,8 +403,56 @@ describe("SwaggerAPI", () => {
 
       expect(result).toEqual({
         success: true,
+        preview: true,
         previewUrl:
           `https://testportal.portal.swaggerhub.com/${productSlug}?preview=product`,
+        product: {
+          id: productResponse.id,
+          name: productResponse.name,
+          slug: productResponse.slug,
+        },
+        portal: {
+          id: portalResponse.id,
+          name: portalResponse.name,
+          subdomain: portalResponse.subdomain,
+          customDomain: undefined,
+        },
+        tableOfContentsItem: null,
+      });
+    });
+
+    it("should use customDomain as the full host when present", async () => {
+      fetchMock
+        .mockResponseOnce(JSON.stringify(productResponse))
+        .mockResponseOnce(JSON.stringify(sectionsResponse))
+        .mockResponseOnce(JSON.stringify(customDomainPortalResponse))
+        .mockResponseOnce(JSON.stringify(publishResponse));
+
+      const result = await api.publishPortalProduct(productId, true, tocId);
+
+      expect(result).toEqual({
+        success: true,
+        preview: true,
+        previewUrl:
+          "https://testCustomDomain.portal-testing.com/test-product/docs/getting-started?preview=product",
+        product: {
+          id: productResponse.id,
+          name: productResponse.name,
+          slug: productResponse.slug,
+        },
+        portal: {
+          id: customDomainPortalResponse.id,
+          name: customDomainPortalResponse.name,
+          subdomain: undefined,
+          customDomain: customDomainPortalResponse.customDomain,
+        },
+        tableOfContentsItem: {
+          id: sectionsResponse.items[0].tableOfContents[0].id,
+          slug: sectionsResponse.items[0].tableOfContents[0].slug,
+          title: sectionsResponse.items[0].tableOfContents[0].title,
+          order: sectionsResponse.items[0].tableOfContents[0].order,
+          parentId: sectionsResponse.items[0].tableOfContents[0].parentId,
+        },
       });
     });
   });