From a5fb7cb0d237440528a03014c9ff82d72016c220 Mon Sep 17 00:00:00 2001
From: Nivedin <53208152+nivedin@users.noreply.github.com>
Date: Tue, 25 Nov 2025 23:06:02 +0530
Subject: [PATCH] fix: API documentation UI flow improvements (#5618)

---
 packages/hoppscotch-common/locales/en.json      |  2 +-
 .../src/components/collections/Collection.vue   | 15 ++++++++++++++-
 .../src/components/collections/Request.vue      | 17 ++++++++++++++++-
 .../collections/documentation/Preview.vue       |  5 ++---
 .../documentation/PublishDocModal.vue           |  1 +
 .../collections/documentation/index.vue         |  8 +++-----
 .../collections/documentation/sections/Auth.vue |  2 +-
 .../documentation/sections/RequestBody.vue      |  4 ++--
 .../documentation/sections/Response.vue         |  9 +++++----
 .../src/components/collections/index.vue        | 16 ----------------
 .../src/components/documentation/Content.vue    |  4 ++--
 .../src/helpers/import-export/import/har.ts     |  2 ++
 .../import/insomnia/insomniaColl.ts             |  6 ++++++
 .../import-export/import/insomnia/types.ts      |  7 ++++++-
 .../import-export/import/openapi/index.ts       | 16 ++++++++++++++++
 .../src/helpers/new-codegen/har.ts              | 15 ++++++++++-----
 .../src/helpers/utils/EffectiveURL.ts           |  3 +--
 17 files changed, 88 insertions(+), 44 deletions(-)

diff --git a/packages/hoppscotch-common/locales/en.json b/packages/hoppscotch-common/locales/en.json
index d70c60f0..8066a1c6 100644
--- a/packages/hoppscotch-common/locales/en.json
+++ b/packages/hoppscotch-common/locales/en.json
@@ -530,7 +530,7 @@
       "copy": "Copy response",
       "example_copied": "Response example copied to clipboard!",
       "example_copy_failed": "Failed to copy response example",
-      "headers": "Headers",
+      "headers": "Response Headers",
       "no_examples": "No response examples available",
       "title": "Response Examples"
     },
diff --git a/packages/hoppscotch-common/src/components/collections/Collection.vue b/packages/hoppscotch-common/src/components/collections/Collection.vue
index 0628d95a..37bbf7b6 100644
--- a/packages/hoppscotch-common/src/components/collections/Collection.vue
+++ b/packages/hoppscotch-common/src/components/collections/Collection.vue
@@ -258,7 +258,7 @@
                     :shortcut="['I']"
                     @click="
                       () => {
-                        emit('open-documentation')
+                        handleDocumentationAction()
                         hide()
                       }
                     "
@@ -683,6 +683,19 @@ const handleMockServerAction = () => {
   emit("create-mock-server")
 }
 
+const handleDocumentationAction = () => {
+  const currentUser = platform.auth.getCurrentUser()
+
+  if (!currentUser) {
+    // Show login modal if user is not authenticated
+    invokeAction("modals.login.toggle")
+    return
+  }
+
+  // User is authenticated, proceed with opening documentation
+  emit("open-documentation")
+}
+
 const resetDragState = () => {
   dragging.value = false
   ordering.value = false
diff --git a/packages/hoppscotch-common/src/components/collections/Request.vue b/packages/hoppscotch-common/src/components/collections/Request.vue
index 488f5d59..628bd5d6 100644
--- a/packages/hoppscotch-common/src/components/collections/Request.vue
+++ b/packages/hoppscotch-common/src/components/collections/Request.vue
@@ -139,7 +139,7 @@
                   :shortcut="['I']"
                   @click="
                     () => {
-                      emit('open-request-documentation')
+                      handleDocumentationAction()
                       hide()
                     }
                   "
@@ -241,6 +241,8 @@ import {
 } from "~/newstore/reordering"
 import { useReadonlyStream } from "~/composables/stream"
 import { getMethodLabelColorClassOf } from "~/helpers/rest/labelColoring"
+import { platform } from "~/platform"
+import { invokeAction } from "~/helpers/actions"
 
 type CollectionType = "my-collections" | "team-collections"
 
@@ -455,6 +457,19 @@ const isRequestLoading = computed(() => {
   return false
 })
 
+const handleDocumentationAction = () => {
+  const currentUser = platform.auth.getCurrentUser()
+
+  if (!currentUser) {
+    // Show login modal if user is not authenticated
+    invokeAction("modals.login.toggle")
+    return
+  }
+
+  // User is authenticated, proceed with opening documentation
+  emit("open-request-documentation")
+}
+
 const resetDragState = () => {
   dragging.value = false
   ordering.value = false
diff --git a/packages/hoppscotch-common/src/components/collections/documentation/Preview.vue b/packages/hoppscotch-common/src/components/collections/documentation/Preview.vue
index 07891362..8d62885e 100644
--- a/packages/hoppscotch-common/src/components/collections/documentation/Preview.vue
+++ b/packages/hoppscotch-common/src/components/collections/documentation/Preview.vue
@@ -356,7 +356,7 @@ const scrollToItem = (id: string): void => {
           block: "start",
         })
       } else {
-        console.log("Item not found:", id)
+        console.error("Item not found:", id)
       }
     }, 50)
   })
@@ -375,10 +375,9 @@ const scrollToItemByNameAndType = (
 
   if (itemIndex !== -1) {
     const targetItem = props.allItems[itemIndex]
-    console.log(`Found ${type} at index: ${itemIndex}`)
     scrollToItem(targetItem.id)
   } else {
-    console.log(`${type} with name "${name}" not found in allItems`)
+    console.error(`${type} with name "${name}" not found in allItems`)
   }
 }
 
diff --git a/packages/hoppscotch-common/src/components/collections/documentation/PublishDocModal.vue b/packages/hoppscotch-common/src/components/collections/documentation/PublishDocModal.vue
index d4fae392..ca3aa07e 100644
--- a/packages/hoppscotch-common/src/components/collections/documentation/PublishDocModal.vue
+++ b/packages/hoppscotch-common/src/components/collections/documentation/PublishDocModal.vue
@@ -76,6 +76,7 @@
 
         <div class="flex space-x-2">
           <HoppButtonPrimary
+            v-if="mode === 'view' || mode === 'update'"
             :label="t('documentation.publish.view_published')"
             :icon="IconExternalLink"
             @click="viewPublished"
diff --git a/packages/hoppscotch-common/src/components/collections/documentation/index.vue b/packages/hoppscotch-common/src/components/collections/documentation/index.vue
index f0287e58..60e1f51c 100644
--- a/packages/hoppscotch-common/src/components/collections/documentation/index.vue
+++ b/packages/hoppscotch-common/src/components/collections/documentation/index.vue
@@ -148,6 +148,7 @@
             </template>
           </tippy>
           <HoppButtonSecondary
+            v-if="currentCollection"
             :icon="isDocumentationProcessing ? IconLoader2 : IconFileText"
             :label="
               isDocumentationProcessing
@@ -427,7 +428,7 @@ const checkPublishedDocsStatus = async () => {
       getTeamPublishedDocs(props.teamID, props.collectionID),
       TE.match(
         (error) => {
-          console.log("No published docs found or error:", error)
+          console.error("No published docs found or error:", error)
           isCheckingPublishedStatus.value = false
         },
         (docs) => {
@@ -454,11 +455,10 @@ const checkPublishedDocsStatus = async () => {
       getUserPublishedDocs(),
       TE.match(
         (error) => {
-          console.log("No published docs found or error:", error)
+          console.error("No published docs found or error:", error)
           isCheckingPublishedStatus.value = false
         },
         (docs) => {
-          console.log("//published-docs///", docs)
           // Find published doc for this collection
           const publishedDoc = docs.find(
             (doc) => doc.collection.id === props.collectionID
@@ -484,9 +484,7 @@ const checkPublishedDocsStatus = async () => {
 watch(
   () => props.show,
   async (newVal) => {
-    console.log("///show///", newVal)
     if (newVal) {
-      console.log("//check-published-docs-status///")
       // Check for existing published docs when modal opens
       await checkPublishedDocsStatus()
     } else {
diff --git a/packages/hoppscotch-common/src/components/collections/documentation/sections/Auth.vue b/packages/hoppscotch-common/src/components/collections/documentation/sections/Auth.vue
index 78bdbedc..b364c7cd 100644
--- a/packages/hoppscotch-common/src/components/collections/documentation/sections/Auth.vue
+++ b/packages/hoppscotch-common/src/components/collections/documentation/sections/Auth.vue
@@ -14,7 +14,7 @@
       <span>{{ t("documentation.auth.title") }}</span>
       <span
         v-if="auth?.authType === 'inherit'"
-        class="ml-2 font-semibold capitalize px-2 py-1 text-tiny rounded bg-divider text-secondaryDark"
+        class="ml-2 font-semibold capitalize px-2 py-1 text-tiny rounded bg-divider text-secondaryDark truncate"
       >
         ({{
           t("documentation.inherited_with_type", {
diff --git a/packages/hoppscotch-common/src/components/collections/documentation/sections/RequestBody.vue b/packages/hoppscotch-common/src/components/collections/documentation/sections/RequestBody.vue
index 3d5b8c7d..7b2cb71e 100644
--- a/packages/hoppscotch-common/src/components/collections/documentation/sections/RequestBody.vue
+++ b/packages/hoppscotch-common/src/components/collections/documentation/sections/RequestBody.vue
@@ -18,7 +18,7 @@
       <!-- Display body content based on type -->
       <div v-if="body.contentType === 'application/json'">
         <pre
-          class="bg-primaryLight p-3 rounded my-2 overflow-auto max-h-64 text-sm font-mono text-secondaryLight"
+          class="bg-primaryLight p-3 rounded my-2 overflow-auto max-h-64 text-xs font-mono text-secondaryLight"
           >{{ formatJSON(body.body) }}</pre
         >
       </div>
@@ -54,7 +54,7 @@
 
       <div v-else>
         <pre
-          class="bg-primaryLight p-3 rounded my-2 overflow-auto max-h-64 text-sm font-mono text-secondaryLight"
+          class="bg-primaryLight p-3 rounded my-2 overflow-auto max-h-64 font-mono text-secondaryLight"
           >{{ body.body }}</pre
         >
       </div>
diff --git a/packages/hoppscotch-common/src/components/collections/documentation/sections/Response.vue b/packages/hoppscotch-common/src/components/collections/documentation/sections/Response.vue
index a1290022..417e3976 100644
--- a/packages/hoppscotch-common/src/components/collections/documentation/sections/Response.vue
+++ b/packages/hoppscotch-common/src/components/collections/documentation/sections/Response.vue
@@ -31,7 +31,7 @@
                 </div>
                 <HoppSmartItem
                   :icon="IconCopy"
-                  :title="t('documentation.copy_response')"
+                  :title="t('documentation.response.copy')"
                   @click="copyResponseExample(example)"
                 />
               </div>
@@ -44,7 +44,7 @@
               <HoppSmartTab
                 v-if="example.body"
                 id="body"
-                :label="t('documentation.response_body')"
+                :label="t('documentation.response.body')"
                 class="flex h-full w-full flex-1 flex-col"
               >
                 <div class="p-4">
@@ -66,7 +66,8 @@
               <HoppSmartTab
                 v-if="example.headers && example.headers.length > 0"
                 id="headers"
-                :label="`${t('documentation.response_headers')} (${example.headers.length})`"
+                :label="t('documentation.response.headers')"
+                :info="`${example.headers.length}`"
                 class="flex h-full w-full flex-1 flex-col"
               >
                 <div class="p-4">
@@ -91,7 +92,7 @@
                         :key="headerIndex"
                         class="border-t border-divider"
                       >
-                        <td class="py-2 px-3 text-accent text-xs">
+                        <td class="py-2 px-3 text-xs">
                           {{ header.key }}
                         </td>
                         <td class="py-2 px-3 text-secondaryLight text-xs">
diff --git a/packages/hoppscotch-common/src/components/collections/index.vue b/packages/hoppscotch-common/src/components/collections/index.vue
index 57731cb8..83737923 100644
--- a/packages/hoppscotch-common/src/components/collections/index.vue
+++ b/packages/hoppscotch-common/src/components/collections/index.vue
@@ -2956,7 +2956,6 @@ const editProperties = async (payload: {
   collection: HoppCollection | TeamCollection
 }) => {
   const { collection, collectionIndex } = payload
-  console.log("collection", collection)
 
   const collectionId = collection.id ?? collectionIndex.split("/").pop()
 
@@ -3270,14 +3269,11 @@ const sortCollections = (payload: {
 
 const openDocumentation = ({
   pathOrID,
-  collectionRefID,
   collection,
 }: {
   pathOrID: string
-  collectionRefID: string
   collection: HoppCollection | TeamCollection
 }) => {
-  console.log("Open documentation for", pathOrID, collectionRefID, collection)
   editingCollectionPath.value = pathOrID
   editingCollection.value = collection
   editingCollectionIsTeam.value =
@@ -3295,24 +3291,12 @@ const openDocumentation = ({
 const openRequestDocumentation = ({
   folderPath,
   requestIndex,
-  requestRefID,
   request,
 }: {
   folderPath: string
   requestIndex: string
-  requestRefID?: string
   request: HoppRESTRequest
 }) => {
-  console.log(
-    "Open documentation for request",
-    folderPath,
-    requestIndex,
-    requestRefID,
-    request
-  )
-  // editingCollectionPath.value = pathOrID
-  // editingCollection.value = collection
-
   editingRequest.value = request
   editingFolderPath.value = folderPath
   editingRequestIndex.value = parseInt(requestIndex)
diff --git a/packages/hoppscotch-common/src/components/documentation/Content.vue b/packages/hoppscotch-common/src/components/documentation/Content.vue
index 5476c01b..0b1f0423 100644
--- a/packages/hoppscotch-common/src/components/documentation/Content.vue
+++ b/packages/hoppscotch-common/src/components/documentation/Content.vue
@@ -133,7 +133,7 @@ const scrollToItem = (id: string): void => {
         block: "start",
       })
     } else {
-      console.log("Item not found:", id)
+      console.error("Item not found:", id)
     }
   }, 100)
 }
@@ -149,7 +149,7 @@ const scrollToItemByName = (name: string, type: "request" | "folder") => {
   if (item) {
     scrollToItem(item.id)
   } else {
-    console.log(`${type} with name "${name}" not found in allItems`)
+    console.error(`${type} with name "${name}" not found in allItems`)
   }
 }
 
diff --git a/packages/hoppscotch-common/src/helpers/import-export/import/har.ts b/packages/hoppscotch-common/src/helpers/import-export/import/har.ts
index 8eaf8175..ec937877 100644
--- a/packages/hoppscotch-common/src/helpers/import-export/import/har.ts
+++ b/packages/hoppscotch-common/src/helpers/import-export/import/har.ts
@@ -37,6 +37,8 @@ export const harImporter = (
         authActive: true,
       },
       headers: [],
+      description: null,
+      variables: [],
     })
 
     return E.right([collection])
diff --git a/packages/hoppscotch-common/src/helpers/import-export/import/insomnia/insomniaColl.ts b/packages/hoppscotch-common/src/helpers/import-export/import/insomnia/insomniaColl.ts
index 66185433..6d1bb907 100644
--- a/packages/hoppscotch-common/src/helpers/import-export/import/insomnia/insomniaColl.ts
+++ b/packages/hoppscotch-common/src/helpers/import-export/import/insomnia/insomniaColl.ts
@@ -228,6 +228,7 @@ const getHoppRequest = (req: InsomniaRequestResource): HoppRESTRequest =>
 
     //insomnia doesn't have saved response
     responses: {},
+    description: req.meta?.description ?? null,
   })
 
 const getHoppFolder = (
@@ -243,6 +244,7 @@ const getHoppFolder = (
     auth: { authType: "inherit", authActive: true },
     headers: [],
     variables: getCollectionVariables(undefined, folderRes), // undefined is used to indicate no environment variables for v4 and below
+    description: folderRes.meta?.description ?? null,
   })
 
 const getHoppCollections = (docs: InsomniaDoc[]) => {
@@ -280,6 +282,7 @@ const getParsedHoppFolder = (
     auth: { authType: "inherit", authActive: true },
     headers: [],
     variables: getCollectionVariables(collection.environment),
+    description: collection.meta.description ?? null,
   })
 }
 
@@ -300,6 +303,8 @@ const getParsedHoppRequest = (req: InsomniaRequestResource) => {
 
     //insomnia doesn't have saved response
     responses: {},
+
+    description: req.meta?.description ?? null,
   })
 }
 
@@ -317,6 +322,7 @@ const getParsedHoppCollections = (docs: InsomniaDocV5[]): HoppCollection[] =>
         auth: { authType: "inherit", authActive: true },
         headers: [],
         variables: getCollectionVariables(doc.environments?.data),
+        description: doc.meta.description ?? null,
       })
     }
 
diff --git a/packages/hoppscotch-common/src/helpers/import-export/import/insomnia/types.ts b/packages/hoppscotch-common/src/helpers/import-export/import/insomnia/types.ts
index 8c7b9980..99fb5474 100644
--- a/packages/hoppscotch-common/src/helpers/import-export/import/insomnia/types.ts
+++ b/packages/hoppscotch-common/src/helpers/import-export/import/insomnia/types.ts
@@ -13,7 +13,11 @@ export type InsomniaPathParameter = {
   value: string
 }
 
-export type InsomniaFolderResource = ImportRequest & { _type: "request_group" }
+export type InsomniaFolderResource = ImportRequest & {
+  _type: "request_group"
+  description?: string
+  meta?: InsomniaMetaV5
+}
 export type InsomniaRequestResource = Omit<
   ImportRequest,
   "headers" | "parameters"
@@ -24,6 +28,7 @@ export type InsomniaRequestResource = Omit<
 } & {
   headers: (Header & { description: string })[]
   parameters: (Parameter & { description: string })[]
+  meta?: InsomniaMetaV5
 }
 
 /**
diff --git a/packages/hoppscotch-common/src/helpers/import-export/import/openapi/index.ts b/packages/hoppscotch-common/src/helpers/import-export/import/openapi/index.ts
index 12941ddd..3aa57bd4 100644
--- a/packages/hoppscotch-common/src/helpers/import-export/import/openapi/index.ts
+++ b/packages/hoppscotch-common/src/helpers/import-export/import/openapi/index.ts
@@ -929,6 +929,7 @@ const convertPathToHoppReqs = (
       } = {
         request: makeRESTRequest({
           name: info.operationId ?? info.summary ?? "Untitled Request",
+          description: info.description ?? null,
           method: method.toUpperCase(),
           endpoint,
 
@@ -1000,6 +1001,17 @@ const convertOpenApiDocsToHopp = (
 
   const collections = docs.map((doc) => {
     const name = doc.info.title
+    const description = doc.info.description ?? null
+
+    // Extract tag descriptions from OpenAPI spec
+    const tagDescriptions: Record<string, string> = {}
+    if ("tags" in doc && Array.isArray(doc.tags)) {
+      doc.tags.forEach((tag: any) => {
+        if (tag.name && tag.description) {
+          tagDescriptions[tag.name] = tag.description
+        }
+      })
+    }
 
     const paths = Object.entries(doc.paths ?? {})
       .map(([pathName, pathObj]) =>
@@ -1032,15 +1044,19 @@ const convertOpenApiDocsToHopp = (
       folders: Object.entries(requestsByTags).map(([name, paths]) =>
         makeCollection({
           name,
+          description: tagDescriptions[name] ?? null,
           requests: paths,
           folders: [],
           auth: { authType: "inherit", authActive: true },
           headers: [],
+          variables: [],
         })
       ),
       requests: requestsWithoutTags,
       auth: { authType: "inherit", authActive: true },
       headers: [],
+      variables: [],
+      description,
     })
   })
 
diff --git a/packages/hoppscotch-common/src/helpers/new-codegen/har.ts b/packages/hoppscotch-common/src/helpers/new-codegen/har.ts
index 7f84f9fd..b8c9e49c 100644
--- a/packages/hoppscotch-common/src/helpers/new-codegen/har.ts
+++ b/packages/hoppscotch-common/src/helpers/new-codegen/har.ts
@@ -67,12 +67,17 @@ const buildHarPostParams = (
   return req.body.body.flatMap((entry) => {
     if (entry.isFile) {
       // We support multiple files
-      return entry.value.map(
+      const values = Array.isArray(entry.value) ? entry.value : [entry.value]
+      return values.map(
         (file) =>
           <Har.Param>{
             name: entry.key,
             fileName: entry.key, // TODO: Blob doesn't contain file info, anyway to bring file name here ?
-            contentType: entry.contentType ? entry.contentType : file?.type,
+            contentType: entry.contentType
+              ? entry.contentType
+              : typeof file === "object" && file && "type" in file
+                ? file.type
+                : undefined,
           }
       )
     }
@@ -80,7 +85,7 @@ const buildHarPostParams = (
     if (entry.contentType) {
       return {
         name: entry.key,
-        value: entry.value,
+        value: entry.value as string,
         fileName: entry.key,
         contentType: entry.contentType,
       }
@@ -88,7 +93,7 @@ const buildHarPostParams = (
 
     return {
       name: entry.key,
-      value: entry.value,
+      value: entry.value as string,
       contentType: entry.contentType,
     }
   })
@@ -111,7 +116,7 @@ const buildHarPostData = (req: HoppRESTRequest): Har.PostData | undefined => {
 
   return {
     mimeType: req.body.contentType, // Let's assume by default content type is JSON
-    text: req.body.body,
+    text: (req.body.body as string) ?? "",
   }
 }
 
diff --git a/packages/hoppscotch-common/src/helpers/utils/EffectiveURL.ts b/packages/hoppscotch-common/src/helpers/utils/EffectiveURL.ts
index 0d8a868d..83545c46 100644
--- a/packages/hoppscotch-common/src/helpers/utils/EffectiveURL.ts
+++ b/packages/hoppscotch-common/src/helpers/utils/EffectiveURL.ts
@@ -314,8 +314,7 @@ export function getFinalBodyFromRequest(
       // we split array blobs into separate entries (FormData will then join them together during exec)
       arrayFlatMap((x) =>
         x.isFile
-          ? // @ts-expect-error TODO: Fix this type error
-            x.value.map((v) => ({
+          ? (Array.isArray(x.value) ? x.value : [x.value]).map((v) => ({
               key: parseTemplateString(x.key, envVariables),
               value: v as string | Blob,
               contentType: x.contentType,