[PR #4187] [MERGED] feat: description field for request parameters and headers #4695

New issue

Closed

opened 2026-03-17 02:12:24 +03:00 by kerem · 0 comments

kerem commented

2026-03-17 02:12:24 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/hoppscotch/hoppscotch/pull/4187
Author: @anwarulislam
Created: 7/14/2024
Status: ✅ Merged
Merged: 8/27/2024
Merged by: @nivedin

Base: next ← Head: feat/params-headers-desc

📝 Commits (10+)

98a5e5c feat: key-value component added for reuse
7612dce chore: inspection result added
f01e8c1 chore: add HoppRESTRequest schema v7
b063a55 feat: add description for field for REST request headers
fb9c211 feat: add description for field for GraphQL request headers
d6a5867 fix: synchronization logic b/w bulk edit context and the default view
a9583bf feat: support importing description fields from external sources
20c783b test: fix failing tests
7ea91ad chore: include description field for computed headers
54da171 feat: add description field for headers at the collection level

📊 Changes

29 files changed (+1347 additions, -1073 deletions)

View changed files

📝 .github/workflows/tests.yml (+2 -2)
📝 packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/multiple-child-collections-auth-headers-coll.json (+614 -614)
📝 packages/hoppscotch-cli/src/__tests__/unit/fixtures/workspace-access.mock.ts (+7 -6)
📝 packages/hoppscotch-cli/src/__tests__/unit/getters.spec.ts (+3 -2)
📝 packages/hoppscotch-common/locales/en.json (+2 -0)
📝 packages/hoppscotch-common/src/components.d.ts (+1 -0)
📝 packages/hoppscotch-common/src/components/collections/Properties.vue (+1 -0)
📝 packages/hoppscotch-common/src/components/graphql/Headers.vue (+109 -132)
📝 packages/hoppscotch-common/src/components/http/Body.vue (+1 -0)
📝 packages/hoppscotch-common/src/components/http/Headers.vue (+113 -140)
➕ packages/hoppscotch-common/src/components/http/KeyValue.vue (+157 -0)
📝 packages/hoppscotch-common/src/components/http/Parameters.vue (+45 -104)
📝 packages/hoppscotch-common/src/helpers/curl/__tests__/curlparser.spec.js (+30 -0)
📝 packages/hoppscotch-common/src/helpers/curl/curlparser.ts (+11 -11)
📝 packages/hoppscotch-common/src/helpers/curl/sub_helpers/headers.ts (+6 -5)
📝 packages/hoppscotch-common/src/helpers/curl/sub_helpers/queries.ts (+4 -3)
📝 packages/hoppscotch-common/src/helpers/import-export/import/insomnia.ts (+8 -2)
📝 packages/hoppscotch-common/src/helpers/import-export/import/openapi.ts (+9 -8)
📝 packages/hoppscotch-common/src/helpers/import-export/import/postman.ts (+37 -18)
📝 packages/hoppscotch-common/src/helpers/utils/EffectiveURL.ts (+6 -0)

...and 9 more files

📄 Description

Description

This PR introduces a new description field for both request parameters and headers in the API documentation. This allows developers to provide clear and concise explanations for each parameter and header, enhancing the readability and usability of the documentation. It is also added for headers at the collection level.

The description field is also accounted for while importing from external sources (Postman, Insomnia & OpenAPI).

A pre-existing issue where edits made to headers from the bulk edit context are not immediately reflected in the default view is resolved.

Closes HFE-535 HFE-538.

Preview

For the auto-generated Authorization and Content-Type headers, the description field will stay disabled and the value will appear empty; while for inherited headers the value specified will be populated.

Changes

Adds a new HttpKeyValue component abstracting the active headers UI and related business logic for reuse across request Parameters & Headers tabs.
Update bulk edit context and the default view synchronization logic accounting for the newly added description field. The description field is excluded while comparing against the key-value pairs from the bulk edit context since it isn't applicable.
Changes to versioned entities:
- HoppCollection schema v3 - Headers at the collection level have an additional description field. Also, the v2 schema is updated to consume HoppRESTHeaders & GQLHeader schema definitions without the description field addition. Also, HoppRESTAuth & HoppGQLAuth schema definitions are consumed from the HoppRESTRequest & HoppGQLRequest v5 schemas instead of from the entry point. This is done so that any field additions at the child level (auth, headers, etc) will require adding a new version for HoppCollection to stay consistent and won't be implicitly supported by the existing latest version as was the case.
  
  Reasoning: Consider the pre-existing scenario where a new field is added under headers HoppRESTHeaders. Assume HoppCollection v2 points to the entry point where the latest version of the above is exported. For an incoming collection conforming to the v2 schema, there is no proper migration mechanism accounting for the description field addition and making it point to the specific HoppRESTHeaders schema and introducing HoppCollection v3 with the relevant migration mechanism adding description field falling back to the value of an empty string ensures proper migration mechanism comes into play and data conforming to the latest version is dealt with.
- HoppRESTRequest schema v7 - New description field for headers and parameters.
- HoppGQLRequest schema v6 - New description field for headers.
Importer module updates to include the description field from external sources.
Updates to test suites and associated fixtures accounting for the internal data structure updates.
Relevant i18n string additions.
Update Node.js CI GH Action workflow config to include next & patch branches as triggers on push & pull_request events.

Note to reviewers

Ensure to verify the following flows:

Specify a description under request parameters/headers for an unsaved request and ensure it persists across page reloads.
Save the request (REST/GQL) under a collection and observe the behaviour. Try exporting (individual/workspace level exports) and importing the same and verify if the description fields are populated. This applies to both personal and team workspaces.
Navigate to the Authorization tab, change the type and observe the Authorization header addition with the description field appearing empty and staying disabled.
Navigate to the bulk edit view and verify edits are synced to and fro.
Open the collection properties modal, specify a description and ensure it persists. For a request inheriting the authorization/header properties, ensure the description field gets populated. Try changing the value at the collection level and verify it gets reflected. Inherited headers will stay disabled at a request level.
Import Postman, Insomnia & OpenAPI collections with descriptions set for request parameters/headers and observe them getting populated while importing.

We're following the convention where any changes under @hoppscotch/data will require a CLI version bump (@hoppscotch/data contents get inlined in the CLI bundle), especially in this case where a new schema definition is added and the CLI would reject a collection conforming to the latest version without publishing the latest changes. The bump is done in #4275 scheduled for the next major release, hence not done in this PR.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/hoppscotch/hoppscotch/pull/4187 **Author:** [@anwarulislam](https://github.com/anwarulislam) **Created:** 7/14/2024 **Status:** ✅ Merged **Merged:** 8/27/2024 **Merged by:** [@nivedin](https://github.com/nivedin) **Base:** `next` ← **Head:** `feat/params-headers-desc` --- ### 📝 Commits (10+) - [`98a5e5c`](https://github.com/hoppscotch/hoppscotch/commit/98a5e5cf6ec375d45978702469965fafb86c7c20) feat: key-value component added for reuse - [`7612dce`](https://github.com/hoppscotch/hoppscotch/commit/7612dce9161d378c906dfa3a4b254a7fe34b89c1) chore: inspection result added - [`f01e8c1`](https://github.com/hoppscotch/hoppscotch/commit/f01e8c1054476920d7acfb3e957c5d415b3b917f) chore: add `HoppRESTRequest` schema `v7` - [`b063a55`](https://github.com/hoppscotch/hoppscotch/commit/b063a55b2defe0926123f605d639f42cb9785107) feat: add `description` for field for REST request headers - [`fb9c211`](https://github.com/hoppscotch/hoppscotch/commit/fb9c211be17028f184175dde44208d0d64f5ea95) feat: add `description` for field for GraphQL request headers - [`d6a5867`](https://github.com/hoppscotch/hoppscotch/commit/d6a5867bec7aea171ccbde40f36c138237d7698c) fix: synchronization logic b/w bulk edit context and the default view - [`a9583bf`](https://github.com/hoppscotch/hoppscotch/commit/a9583bfe7d638c2f292ff3404e0cb412e6527742) feat: support importing `description` fields from external sources - [`20c783b`](https://github.com/hoppscotch/hoppscotch/commit/20c783b9786462f17d25404471ad55b6e1c05f16) test: fix failing tests - [`7ea91ad`](https://github.com/hoppscotch/hoppscotch/commit/7ea91adf0e31d3f7921ab2fef9ad8892f3cc7fe2) chore: include description field for computed headers - [`54da171`](https://github.com/hoppscotch/hoppscotch/commit/54da171b2961bebc6ef809841f669de0925987e0) feat: add `description` field for headers at the collection level ### 📊 Changes **29 files changed** (+1347 additions, -1073 deletions) <details> <summary>View changed files</summary> 📝 `.github/workflows/tests.yml` (+2 -2) 📝 `packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/multiple-child-collections-auth-headers-coll.json` (+614 -614) 📝 `packages/hoppscotch-cli/src/__tests__/unit/fixtures/workspace-access.mock.ts` (+7 -6) 📝 `packages/hoppscotch-cli/src/__tests__/unit/getters.spec.ts` (+3 -2) 📝 `packages/hoppscotch-common/locales/en.json` (+2 -0) 📝 `packages/hoppscotch-common/src/components.d.ts` (+1 -0) 📝 `packages/hoppscotch-common/src/components/collections/Properties.vue` (+1 -0) 📝 `packages/hoppscotch-common/src/components/graphql/Headers.vue` (+109 -132) 📝 `packages/hoppscotch-common/src/components/http/Body.vue` (+1 -0) 📝 `packages/hoppscotch-common/src/components/http/Headers.vue` (+113 -140) ➕ `packages/hoppscotch-common/src/components/http/KeyValue.vue` (+157 -0) 📝 `packages/hoppscotch-common/src/components/http/Parameters.vue` (+45 -104) 📝 `packages/hoppscotch-common/src/helpers/curl/__tests__/curlparser.spec.js` (+30 -0) 📝 `packages/hoppscotch-common/src/helpers/curl/curlparser.ts` (+11 -11) 📝 `packages/hoppscotch-common/src/helpers/curl/sub_helpers/headers.ts` (+6 -5) 📝 `packages/hoppscotch-common/src/helpers/curl/sub_helpers/queries.ts` (+4 -3) 📝 `packages/hoppscotch-common/src/helpers/import-export/import/insomnia.ts` (+8 -2) 📝 `packages/hoppscotch-common/src/helpers/import-export/import/openapi.ts` (+9 -8) 📝 `packages/hoppscotch-common/src/helpers/import-export/import/postman.ts` (+37 -18) 📝 `packages/hoppscotch-common/src/helpers/utils/EffectiveURL.ts` (+6 -0) _...and 9 more files_ </details> ### 📄 Description ### Description This PR introduces a new `description` field for both request parameters and headers in the API documentation. This allows developers to provide clear and concise explanations for each parameter and header, enhancing the readability and usability of the documentation. It is also added for headers at the collection level. The `description` field is also accounted for while importing from external sources (`Postman`, `Insomnia` & `OpenAPI`). A pre-existing issue where edits made to headers from the bulk edit context are not immediately reflected in the default view is resolved. Closes HFE-535 HFE-538. ### Preview ![image](https://github.com/user-attachments/assets/d4b2edde-486b-4c83-ba8e-003049494ea2) > For the auto-generated `Authorization` and `Content-Type` headers, the `description` field will stay disabled and the value will appear empty; while for inherited headers the value specified will be populated. ![header-desc](https://github.com/user-attachments/assets/1a40e2dc-040c-4759-8da0-7e94d5ca9457) ### Changes - Adds a new `HttpKeyValue` component abstracting the active headers UI and related business logic for reuse across request `Parameters` & `Headers` tabs. - Update bulk edit context and the default view synchronization logic accounting for the newly added `description` field. The `description` field is excluded while comparing against the key-value pairs from the bulk edit context since it isn't applicable. - Changes to versioned entities: - `HoppCollection` schema `v3` - Headers at the collection level have an additional `description` field. Also, the `v2` schema is updated to consume `HoppRESTHeaders` & `GQLHeader` schema definitions without the `description` field addition. Also, `HoppRESTAuth` & `HoppGQLAuth` schema definitions are consumed from the `HoppRESTRequest` & `HoppGQLRequest` `v5` schemas instead of from the entry point. This is done so that any field additions at the child level (`auth`, `headers`, etc) will require adding a new version for `HoppCollection` to stay consistent and won't be implicitly supported by the existing latest version as was the case. > Reasoning: Consider the pre-existing scenario where a new field is added under headers `HoppRESTHeaders`. Assume `HoppCollection` `v2` points to the entry point where the latest version of the above is exported. For an incoming collection conforming to the `v2` schema, there is no proper migration mechanism accounting for the `description` field addition and making it point to the specific `HoppRESTHeaders` schema and introducing `HoppCollection` `v3` with the relevant migration mechanism adding `description` field falling back to the value of an empty string ensures proper migration mechanism comes into play and data conforming to the latest version is dealt with. - `HoppRESTRequest` schema `v7` - New `description` field for headers and parameters. - `HoppGQLRequest` schema `v6` - New `description` field for headers. - Importer module updates to include the `description` field from external sources. - Updates to test suites and associated fixtures accounting for the internal data structure updates. - Relevant `i18n` string additions. - Update `Node.js CI` GH Action workflow config to include `next` & `patch` branches as triggers on `push` & `pull_request` events. ### Note to reviewers Ensure to verify the following flows: - Specify a description under request parameters/headers for an unsaved request and ensure it persists across page reloads. - Save the request (`REST`/`GQL`) under a collection and observe the behaviour. Try exporting (individual/workspace level exports) and importing the same and verify if the `description` fields are populated. This applies to both personal and team workspaces. - Navigate to the `Authorization` tab, change the type and observe the `Authorization` header addition with the `description` field appearing empty and staying disabled. - Navigate to the bulk edit view and verify edits are synced to and fro. - Open the collection properties modal, specify a description and ensure it persists. For a request inheriting the authorization/header properties, ensure the `description` field gets populated. Try changing the value at the collection level and verify it gets reflected. Inherited headers will stay disabled at a request level. - Import Postman, Insomnia & OpenAPI collections with descriptions set for request parameters/headers and observe them getting populated while importing. We're following the convention where any changes under `@hoppscotch/data` will require a CLI version bump (`@hoppscotch/data` contents get inlined in the CLI bundle), especially in this case where a new schema definition is added and the CLI would reject a collection conforming to the latest version without publishing the latest changes. The bump is done in #4275 scheduled for the next major release, hence not done in this PR. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>