[PR #5676] [MERGED] feat: api documentation versioning #5313

New issue

Closed

opened 2026-03-17 02:46:21 +03:00 by kerem · 0 comments

kerem commented

2026-03-17 02:46:21 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/hoppscotch/hoppscotch/pull/5676
Author: @mirarifhasan
Created: 12/8/2025
Status: ✅ Merged
Merged: 2/23/2026
Merged by: @jamesgeorge007

Base: next ← Head: feat/api-doc-versioning

📝 Commits (10+)

43771fc feat: add slug to PublishedDocs and update API endpoints
c90c110 chore: add schema validation and published docs URL field
ec44edd test: fix broken test cases
05ebbce fix: documentTree when update autoSync and allowed public api to call without version
0d3a371 feat: add environment support to PublishedDocs
ff061a5 feat: introduce documentation versioning
29fd344 chore: add environment picker and version snapshot
66fbf9e chore: remove log statements
a27dd1b chore: cleanup
bfd52dc chore: update test and cleanup

📊 Changes

37 files changed (+3438 additions, -477 deletions)

View changed files

➕ packages/hoppscotch-backend/prisma/migrations/20251207122817_add_slug_to_published_docs/migration.sql (+31 -0)
➕ packages/hoppscotch-backend/prisma/migrations/20260209063744_published_doc_environment/migration.sql (+4 -0)
📝 packages/hoppscotch-backend/prisma/schema.prisma (+19 -12)
📝 packages/hoppscotch-backend/src/errors.ts (+7 -0)
📝 packages/hoppscotch-backend/src/published-docs/input-type.args.ts (+21 -0)
📝 packages/hoppscotch-backend/src/published-docs/published-docs.controller.ts (+38 -11)
➖ packages/hoppscotch-backend/src/published-docs/published-docs.dto.ts (+0 -19)
📝 packages/hoppscotch-backend/src/published-docs/published-docs.model.ts (+124 -0)
📝 packages/hoppscotch-backend/src/published-docs/published-docs.resolver.ts (+19 -1)
📝 packages/hoppscotch-backend/src/published-docs/published-docs.service.spec.ts (+943 -54)
📝 packages/hoppscotch-backend/src/published-docs/published-docs.service.ts (+280 -27)
📝 packages/hoppscotch-backend/src/team-collection/team-collection.service.ts (+14 -17)
📝 packages/hoppscotch-backend/src/user-collection/user-collection.service.ts (+19 -22)
📝 packages/hoppscotch-common/locales/en.json (+27 -1)
📝 packages/hoppscotch-common/src/components.d.ts (+11 -0)
📝 packages/hoppscotch-common/src/components/collections/documentation/CollectionStructure.vue (+6 -3)
➕ packages/hoppscotch-common/src/components/collections/documentation/EnvironmentPicker.vue (+191 -0)
📝 packages/hoppscotch-common/src/components/collections/documentation/Preview.vue (+1 -0)
➕ packages/hoppscotch-common/src/components/collections/documentation/PublishDocForm.vue (+169 -0)
📝 packages/hoppscotch-common/src/components/collections/documentation/PublishDocModal.vue (+64 -101)

...and 17 more files

📄 Description

Closes BE-685 FE-1124

What's changed

Backend Changes

Adds stable slugs to PublishedDocs and a new public endpoint to fetch docs by slug and version, enabling consistent URLs and version lists. The old id-based endpoint remains but is deprecated.

New Features

Added slug to PublishedDocs with unique (slug, version); migration backfills slug=id and removes duplicate docs per collection+version.
New public endpoint: GET /published-docs/:slug/:version; id-based route kept but deprecated.
GraphQL: PublishedDocs includes slug and versions[] resolver returns all versions for the slug.
createPublishedDoc reuses a collection’s slug for new versions, retries on unique constraint races, and snapshots documentTree when autoSync=false.
URL generation now uses slug/version.

Database Migration

Run pnpx prisma migrate deploy

Frontend Changes

https://github.com/user-attachments/assets/9fff4d4c-82a2-4487-8477-1518b1e04fb5

Notes to reviewers

Run DB migration.

Summary by cubic

Adds slug-based, versioned public URLs for PublishedDocs with read-only snapshots and optional environment attachments. Replaces id-based routes, adds a versions list and environment toggle in the UI, and fixes live version detection. Aligns with BE-685 and FE-1124.

New Features
- Backend: unique (slug, version) index; slugs backfilled and enforced; public GET /published-docs/:slug (latest) and /:slug/:version; id route and tree param removed; invalid environment errors surfaced.
- GraphQL: PublishedDocs exposes slug, environmentName/environmentVariables, metadata, URL, and versions[] resolver.
- Create/update: reuse collection slug; snapshot documentTree when autoSync=false; clear when autoSync=true; retry on unique races.
- Environment: optional environmentID with validation; env name/vars injected into public cURL/request previews; header adds environment toggle and version dropdown with CURRENT tag.
- Frontend: EnvironmentPicker, PublishDocForm, and SnapshotPreview; compact sidebar/modal polish; custom ID escaping replaces CSS.escape; EffectiveURL can show keys when values are missing.
- Tests: expanded unit tests for versioning (including versions resolver), isLiveVersion, and environment handling.
Migration
- Run prisma migrate; backfill slugs (slug=id), dedupe per collection+version, and add environment columns.
- Update clients to use slug-based endpoints, show versions, and pass optional environmentID; remove id-based links and the tree query param.

^{Written for commit 756465f7ad. Summary will update on new commits.}

_{🔄 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/5676 **Author:** [@mirarifhasan](https://github.com/mirarifhasan) **Created:** 12/8/2025 **Status:** ✅ Merged **Merged:** 2/23/2026 **Merged by:** [@jamesgeorge007](https://github.com/jamesgeorge007) **Base:** `next` ← **Head:** `feat/api-doc-versioning` --- ### 📝 Commits (10+) - [`43771fc`](https://github.com/hoppscotch/hoppscotch/commit/43771fc343bc109ff8ef72d85a2616d40e561ccc) feat: add slug to PublishedDocs and update API endpoints - [`c90c110`](https://github.com/hoppscotch/hoppscotch/commit/c90c110ed4be91f000f2ab439a8122cd5a73d82d) chore: add schema validation and published docs URL field - [`ec44edd`](https://github.com/hoppscotch/hoppscotch/commit/ec44edd805aa4cb8f80bc15ba1b5640d4328158b) test: fix broken test cases - [`05ebbce`](https://github.com/hoppscotch/hoppscotch/commit/05ebbcefe503d278b530503e18299d825732e3b7) fix: documentTree when update autoSync and allowed public api to call without version - [`0d3a371`](https://github.com/hoppscotch/hoppscotch/commit/0d3a371ef6ef9e61e66b7d3c896551552585829d) feat: add environment support to PublishedDocs - [`ff061a5`](https://github.com/hoppscotch/hoppscotch/commit/ff061a517bb92e347a9b9c4e3def0da264c1f72c) feat: introduce documentation versioning - [`29fd344`](https://github.com/hoppscotch/hoppscotch/commit/29fd344262f101edc58121f70dd3538653f7fc79) chore: add environment picker and version snapshot - [`66fbf9e`](https://github.com/hoppscotch/hoppscotch/commit/66fbf9efc24a26e508cea188ba8338da2da61767) chore: remove log statements - [`a27dd1b`](https://github.com/hoppscotch/hoppscotch/commit/a27dd1b894518d662a940f9e9a96560595cfb7a8) chore: cleanup - [`bfd52dc`](https://github.com/hoppscotch/hoppscotch/commit/bfd52dc5eb9e5662a53d1bcbc8299d7a72f05f54) chore: update test and cleanup ### 📊 Changes **37 files changed** (+3438 additions, -477 deletions) <details> <summary>View changed files</summary> ➕ `packages/hoppscotch-backend/prisma/migrations/20251207122817_add_slug_to_published_docs/migration.sql` (+31 -0) ➕ `packages/hoppscotch-backend/prisma/migrations/20260209063744_published_doc_environment/migration.sql` (+4 -0) 📝 `packages/hoppscotch-backend/prisma/schema.prisma` (+19 -12) 📝 `packages/hoppscotch-backend/src/errors.ts` (+7 -0) 📝 `packages/hoppscotch-backend/src/published-docs/input-type.args.ts` (+21 -0) 📝 `packages/hoppscotch-backend/src/published-docs/published-docs.controller.ts` (+38 -11) ➖ `packages/hoppscotch-backend/src/published-docs/published-docs.dto.ts` (+0 -19) 📝 `packages/hoppscotch-backend/src/published-docs/published-docs.model.ts` (+124 -0) 📝 `packages/hoppscotch-backend/src/published-docs/published-docs.resolver.ts` (+19 -1) 📝 `packages/hoppscotch-backend/src/published-docs/published-docs.service.spec.ts` (+943 -54) 📝 `packages/hoppscotch-backend/src/published-docs/published-docs.service.ts` (+280 -27) 📝 `packages/hoppscotch-backend/src/team-collection/team-collection.service.ts` (+14 -17) 📝 `packages/hoppscotch-backend/src/user-collection/user-collection.service.ts` (+19 -22) 📝 `packages/hoppscotch-common/locales/en.json` (+27 -1) 📝 `packages/hoppscotch-common/src/components.d.ts` (+11 -0) 📝 `packages/hoppscotch-common/src/components/collections/documentation/CollectionStructure.vue` (+6 -3) ➕ `packages/hoppscotch-common/src/components/collections/documentation/EnvironmentPicker.vue` (+191 -0) 📝 `packages/hoppscotch-common/src/components/collections/documentation/Preview.vue` (+1 -0) ➕ `packages/hoppscotch-common/src/components/collections/documentation/PublishDocForm.vue` (+169 -0) 📝 `packages/hoppscotch-common/src/components/collections/documentation/PublishDocModal.vue` (+64 -101) _...and 17 more files_ </details> ### 📄 Description    Closes BE-685 FE-1124  ### What's changed  #### Backend Changes Adds stable slugs to PublishedDocs and a new public endpoint to fetch docs by slug and version, enabling consistent URLs and version lists. The old id-based endpoint remains but is deprecated. New Features - Added slug to PublishedDocs with unique (slug, version); migration backfills `slug=id` and removes duplicate docs per collection+version. - New public endpoint: GET /published-docs/:slug/:version; id-based route kept but deprecated. - GraphQL: `PublishedDocs` includes `slug` and `versions[]` resolver returns all versions for the slug. - `createPublishedDoc` reuses a collection’s slug for new versions, retries on unique constraint races, and snapshots documentTree when `autoSync=false`. - URL generation now uses slug/version. Database Migration - Run `pnpx prisma migrate deploy` --- #### Frontend Changes https://github.com/user-attachments/assets/9fff4d4c-82a2-4487-8477-1518b1e04fb5  ### Notes to reviewers  Run DB migration.  --- ## Summary by cubic Adds slug-based, versioned public URLs for PublishedDocs with read-only snapshots and optional environment attachments. Replaces id-based routes, adds a versions list and environment toggle in the UI, and fixes live version detection. Aligns with BE-685 and FE-1124. - **New Features** - Backend: unique (slug, version) index; slugs backfilled and enforced; public GET /published-docs/:slug (latest) and /:slug/:version; id route and tree param removed; invalid environment errors surfaced. - GraphQL: PublishedDocs exposes slug, environmentName/environmentVariables, metadata, URL, and versions[] resolver. - Create/update: reuse collection slug; snapshot documentTree when autoSync=false; clear when autoSync=true; retry on unique races. - Environment: optional environmentID with validation; env name/vars injected into public cURL/request previews; header adds environment toggle and version dropdown with CURRENT tag. - Frontend: EnvironmentPicker, PublishDocForm, and SnapshotPreview; compact sidebar/modal polish; custom ID escaping replaces CSS.escape; EffectiveURL can show keys when values are missing. - Tests: expanded unit tests for versioning (including versions resolver), isLiveVersion, and environment handling. - **Migration** - Run prisma migrate; backfill slugs (slug=id), dedupe per collection+version, and add environment columns. - Update clients to use slug-based endpoints, show versions, and pass optional environmentID; remove id-based links and the tree query param. <sup>Written for commit 756465f7adf9156ec2d5c933a6b93c110789fe99. Summary will update on new commits.</sup>  --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>