feat and fix(docs): mgmt api pipeline and postman collection by aidankmcalister · Pull Request #7888 · prisma/web

aidankmcalister · 2026-05-11T00:35:25Z

Summary

DR-8103: Rewrites the management API doc generation pipeline to handle stale directories, missing sidebar entries, and 404s when endpoints are removed. generate-docs.ts is now a proper async script that diffs old vs new URLs, writes redirects to vercel.json without reformatting the file, cleans up empty tag directories, and auto-syncs endpoints/meta.json. Also omits [experimental] endpoints from the published docs.
DR-8543: Adds a generate-postman-collection.ts script that converts the cached OpenAPI spec to a Postman Collection v2.1 file, served statically and linked from the API clients page. Collection has OAuth2 pre-configured, query params disabled by default, duplicate names disambiguated, and experimental endpoints excluded.

Test plan

Run pnpm generate:management-api-docs from apps/docs — confirm new MDX files generated, stale files deleted, meta.json updated, no vercel.json reformatting
Run pnpm generate:postman-collection — confirm public/prisma-management-api.postman_collection.json is created
Import the collection into Postman — confirm OAuth2 auth present, query params unchecked, no duplicate request names, no [Experimental] folder
Visit /management-api/api-clients — confirm download link triggers a file save

Summary by CodeRabbit

New Features
- Added downloadable Postman collection for Management API, compatible with Postman, Yaak, Insomnia, and other OpenAPI-compatible clients
Documentation
- Reorganized Management API endpoint documentation structure
- Removed experimental endpoint documentation pages

- Rewrite generate-docs.ts as async main() that collects existing endpoint URLs before generating, then diffs old vs new to prepend redirects to vercel.json for removed endpoints (raw string ops, no reformatting) - Remove stale MDX files and empty tag directories after each run - Auto-sync endpoints/meta.json: preserve order, append new dirs alphabetically, always put [experimental] last - Fix meta.json to add missing connections, regions, and [experimental] dirs - Omit [experimental] endpoints from published docs entirely Linear: DR-8103

- Add generate-postman-collection.ts script that converts the cached OpenAPI spec to Postman Collection v2.1 using openapi-to-postmanv2 - Pre-configure OAuth2 auth (auth.prisma.io, workspace:admin scope) - Disable all query params by default (visible but unchecked, toggleable) - Deduplicate request names that share a summary but have different paths - Omit [experimental] folder from collection - Output to public/ so the file is statically served - Wire into generate:management-api-docs so it runs on every sync - Add download link to api-clients.mdx above the client sections - Update sync workflow to commit the collection and vercel.json Linear: DR-8543

vercel · 2026-05-11T00:35:31Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
blog	Ready	Preview, Comment	May 11, 2026 0:36am
docs	Ready	Preview, Comment	May 11, 2026 0:36am
eclipse	Ready	Preview, Comment	May 11, 2026 0:36am
site	Ready	Preview, Comment	May 11, 2026 0:36am

github-actions · 2026-05-11T00:36:11Z

🍈 Lychee Link Check Report

5 links: ✅ 2 OK | 🚫 0 errors | 🔀 2 redirects | 👻 1 excluded

✅ All links are working!

Full Statistics Table

Status	Count
✅ Successful	2
🔀 Redirected	2
👻 Excluded	1
🚫 Errors	0
⛔ Unsupported	0
⏳ Timeouts	0
❓ Unknown	0

coderabbitai · 2026-05-11T00:36:30Z

Walkthrough

This PR refactors the Management API documentation generation pipeline to generate a Postman collection from the OpenAPI spec, implement incremental file reconciliation (avoiding delete-and-regenerate), auto-sync vercel.json redirects, filter experimental endpoints, and provide a downloadable collection link in the docs.

Changes

Management API Documentation Generation Pipeline

Layer / File(s)	Summary
Generation Script Core Refactor `apps/docs/scripts/generate-docs.ts`	Wraps generation in async `main()`, scans existing files to map `url → path`, uses `generateFilesOnly` with `beforeWrite` hook to normalize frontmatter fields (`_openapi`, `url`, `metaTitle`, `description`, `metaDescription`), filters out `[experimental]` endpoints, computes stale files by comparing pre-existing vs. generated sets, syncs `vercel.json` by removing stale/restored redirects and prepending new ones in compact single-line format, updates `meta.json` by preserving existing order and appending new tags alphabetically with `[experimental]` last, and removes stale `.mdx` files and empty directories.
Postman Collection Generation `apps/docs/scripts/generate-postman-collection.ts`	New script converts OpenAPI spec from cache to Postman Collection v2.1 using `openapi-to-postmanv2`, removes `[Experimental]` folder, deduplicates request names by appending normalized URL path segments, marks all query parameters `disabled: true` by default, pre-configures OAuth2 auth with Prisma endpoints, and writes final collection to `public/prisma-management-api.postman_collection.json`.
Dependencies and Build Configuration `apps/docs/package.json`	Script `generate:management-api-docs` now chains `generate:postman-collection` (removes prior `rimraf` cleanup). New dev dependency `openapi-to-postmanv2` at `^6.0.1`.
Workflow Integration `.github/workflows/sync-management-api-docs.yml`	Narrowed `git status` checks to management API docs directory, Postman collection JSON, and `apps/docs/vercel.json`; stages only those paths instead of entire docs directory.
Documentation and Metadata Updates `apps/docs/content/docs/management-api/api-clients.mdx`, `apps/docs/content/docs/management-api/endpoints/meta.json`	Added downloadable Postman collection link referencing `/docs/prisma-management-api.postman_collection.json` with compatibility notes for Postman, Yaak, Insomnia, and Postman Collection v2.1 clients. Reordered `pages` list in `meta.json` to place `"connections"` and `"regions"` after `"workspaces"`.
Experimental Endpoints Removal `apps/docs/content/docs/management-api/endpoints/[experimental]/*`	Removed 33 experimental endpoint MDX pages: `DELETE /v1/branches/{branchId}`, `DELETE /v1/compute-services/{computeServiceId}`, `DELETE /v1/compute-services/versions/{versionId}`, `DELETE /v1/environment-variables/{envVarId}`, `DELETE /v1/versions/{versionId}`, `GET /v1/branches/{branchId}`, `GET /v1/compute-services`, `GET /v1/compute-services/{computeServiceId}`, `GET /v1/compute-services/{computeServiceId}/versions`, `GET /v1/compute-services/versions/{versionId}`, `GET /v1/compute-services/versions/{versionId}/logs`, `GET /v1/environment-variables`, `GET /v1/environment-variables/{envVarId}`, `GET /v1/projects/{projectId}/branches`, `GET /v1/projects/{projectId}/compute-services`, `GET /v1/versions`, `GET /v1/versions/{versionId}`, `PATCH /v1/branches/{branchId}`, `PATCH /v1/compute-services/{computeServiceId}`, `PATCH /v1/environment-variables/{envVarId}`, `POST /v1/compute-services`, `POST /v1/compute-services/{computeServiceId}/promote`, `POST /v1/compute-services/{computeServiceId}/versions`, `POST /v1/compute-services/versions/{versionId}/start`, `POST /v1/compute-services/versions/{versionId}/stop`, `POST /v1/environment-variables`, `POST /v1/projects/{projectId}/branches`, `POST /v1/projects/{projectId}/compute-services`, `POST /v1/versions`, `POST /v1/versions/{versionId}/start`, `POST /v1/versions/{versionId}/stop`.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.50% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: it's a feature and fix for the documentation generation pipeline (refactoring generate-docs.ts) plus the addition of a Postman collection. Both are clearly the primary objectives of this PR.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

argos-ci · 2026-05-11T00:38:34Z

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ No changes detected	-	May 11, 2026, 12:44 AM

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/docs/scripts/generate-docs.ts`:
- Around line 149-150: The mapping newUrlToRelPath is being populated for every
generated file (using file.path), which causes experimental pages to be treated
as published when redirect reconciliation runs; change the logic in the
generation loop (where newUrlToRelPath.set(url, file.path.replace(/\\/g, "/"))
is called) to first check whether the file is marked experimental (e.g.,
contains "[experimental]" or whatever flag/file.meta you use) and only add to
newUrlToRelPath for non-experimental files; apply the same guard to the other
similar spots mentioned (the blocks around lines that currently set mappings at
195-198 and 218-240) so experimental files are excluded from the published URL
set.

In `@apps/docs/scripts/generate-postman-collection.ts`:
- Around line 72-76: When deduping names in the loop over item.item the code
only appends the path (pathStr) which still collides when two operations share
the same summary and path but use different HTTP methods; update the renaming so
it also appends the request method (use r.request?.method, normalized to
upper-case or fallback like "UNKNOWN") along with pathStr when constructing
r.name (e.g., include `${method} ${pathStr}`) to guarantee uniqueness across
different HTTP verbs and handle missing method safely.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: b6b2abf7-9011-4cde-80c0-07e0b2a543f4

📥 Commits

Reviewing files that changed from the base of the PR and between d0a17f2 and 2e60518.

⛔ Files ignored due to path filters (1)

pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (38)

.github/workflows/sync-management-api-docs.yml
apps/docs/content/docs/management-api/api-clients.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/delete-branches-by-branch-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/delete-compute-services-by-compute-service-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/delete-compute-services-versions-by-version-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/delete-environment-variables-by-env-var-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/delete-versions-by-version-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-branches-by-branch-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-compute-services-by-compute-service-id-versions.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-compute-services-by-compute-service-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-compute-services-versions-by-version-id-logs.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-compute-services-versions-by-version-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-compute-services.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-environment-variables-by-env-var-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-environment-variables.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-projects-by-project-id-branches.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-projects-by-project-id-compute-services.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-versions-by-version-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-versions.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/patch-branches-by-branch-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/patch-compute-services-by-compute-service-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/patch-environment-variables-by-env-var-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-compute-services-by-compute-service-id-promote.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-compute-services-by-compute-service-id-versions.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-compute-services-versions-by-version-id-start.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-compute-services-versions-by-version-id-stop.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-compute-services.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-environment-variables.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-projects-by-project-id-branches.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-projects-by-project-id-compute-services.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-versions-by-version-id-start.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-versions-by-version-id-stop.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-versions.mdx
apps/docs/content/docs/management-api/endpoints/meta.json
apps/docs/package.json
apps/docs/public/prisma-management-api.postman_collection.json
apps/docs/scripts/generate-docs.ts
apps/docs/scripts/generate-postman-collection.ts

💤 Files with no reviewable changes (31)

apps/docs/content/docs/management-api/endpoints/[experimental]/get-projects-by-project-id-compute-services.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/delete-environment-variables-by-env-var-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/delete-branches-by-branch-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-projects-by-project-id-branches.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-compute-services-by-compute-service-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-branches-by-branch-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-versions-by-version-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-compute-services-versions-by-version-id-start.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-versions.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-projects-by-project-id-compute-services.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-versions-by-version-id-stop.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/patch-branches-by-branch-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-versions-by-version-id-start.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-versions.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-compute-services-by-compute-service-id-versions.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-projects-by-project-id-branches.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-compute-services-versions-by-version-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-environment-variables.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-compute-services.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-environment-variables.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-compute-services-versions-by-version-id-logs.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/delete-versions-by-version-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-compute-services-versions-by-version-id-stop.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-compute-services.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/post-compute-services-by-compute-service-id-promote.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/delete-compute-services-versions-by-version-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/patch-compute-services-by-compute-service-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/delete-compute-services-by-compute-service-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-compute-services-by-compute-service-id-versions.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/get-environment-variables-by-env-var-id.mdx
apps/docs/content/docs/management-api/endpoints/[experimental]/patch-environment-variables-by-env-var-id.mdx

aidankmcalister added 2 commits May 10, 2026 20:33

vercel Bot deployed to Preview – eclipse May 11, 2026 00:35 View deployment

vercel Bot deployed to Preview – site May 11, 2026 00:35 View deployment

vercel Bot deployed to Preview – docs May 11, 2026 00:36 View deployment

coderabbitai Bot reviewed May 11, 2026

View reviewed changes

Comment thread apps/docs/scripts/generate-docs.ts

Comment thread apps/docs/scripts/generate-postman-collection.ts

mhessdev approved these changes May 11, 2026

View reviewed changes

mhartington approved these changes May 11, 2026

View reviewed changes

aidankmcalister merged commit e9ef439 into main May 11, 2026
17 checks passed

aidankmcalister deleted the feat-and-fix/mgmt-api-pipeline-and-postman-collection branch May 11, 2026 13:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat and fix(docs): mgmt api pipeline and postman collection#7888

feat and fix(docs): mgmt api pipeline and postman collection#7888
aidankmcalister merged 2 commits intomainfrom
feat-and-fix/mgmt-api-pipeline-and-postman-collection

aidankmcalister commented May 11, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

vercel Bot commented May 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 11, 2026

Uh oh!

coderabbitai Bot commented May 11, 2026 •

edited

Loading

❌ Failed checks (1 warning)

Uh oh!

argos-ci Bot commented May 11, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

aidankmcalister commented May 11, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Summary by CodeRabbit

Uh oh!

vercel Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented May 11, 2026

🍈 Lychee Link Check Report

✅ All links are working!

Uh oh!

coderabbitai Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

❌ Failed checks (1 warning)

Uh oh!

argos-ci Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

aidankmcalister commented May 11, 2026 •

edited by coderabbitai Bot

Loading

vercel Bot commented May 11, 2026 •

edited

Loading

coderabbitai Bot commented May 11, 2026 •

edited

Loading

argos-ci Bot commented May 11, 2026 •

edited

Loading