fix(docs): generate valid management-api endpoint metadata and unique filenames#7592
Open
aidankmcalister wants to merge 2 commits intomainfrom
Open
fix(docs): generate valid management-api endpoint metadata and unique filenames#7592aidankmcalister wants to merge 2 commits intomainfrom
aidankmcalister wants to merge 2 commits intomainfrom
Conversation
Contributor
WalkthroughThis pull request introduces comprehensive documentation for Management API endpoints by adding 29 new MDX documentation files, refactoring metadata structure in existing documentation, and enhancing the documentation generation script to support improved front matter handling and PATCH method support. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes This change involves a large cohort of homogeneous new documentation files (which require minimal individual review) paired with several moderate-complexity modifications: the script refactor in 🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 11
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
apps/docs/src/app/og/[...slug]/route.tsx (1)
38-53:⚠️ Potential issue | 🟡 MinorNormalize and validate method before rendering the badge.
On Line 38 and Line 53, the fallback color makes
methodColortruthy for any non-empty string, so unsupported/typo methods still render as valid-looking badges. This can mask bad metadata.Suggested fix
- const methodColor = method ? HTTP_METHOD_COLORS[method as keyof typeof HTTP_METHOD_COLORS] ?? "#71e8df" : null; + const normalizedMethod = method?.trim().toUpperCase(); + const methodColor = + normalizedMethod && normalizedMethod in HTTP_METHOD_COLORS + ? HTTP_METHOD_COLORS[normalizedMethod as keyof typeof HTTP_METHOD_COLORS] + : null; ... - {method && methodColor ? ( + {normalizedMethod && methodColor ? ( ... - {method} + {normalizedMethod}Also applies to: 73-74
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/app/og/`[...slug]/route.tsx around lines 38 - 53, Normalize and validate the HTTP method before using it to pick a color: convert the incoming method to a canonical form (e.g., methodNormalized = method?.toUpperCase()) and only set methodColor from HTTP_METHOD_COLORS if HTTP_METHOD_COLORS hasOwnProperty(methodNormalized); otherwise set methodColor to null so unsupported/typo values don't render a badge. Update the code that computes methodColor and any other badge rendering sites (the other occurrence using method/HTTP_METHOD_COLORS) to use methodNormalized and the explicit presence check rather than relying on the fallback color.apps/docs/content/docs/management-api/endpoints/databases/patch-databases-id.mdx (1)
1-21:⚠️ Potential issue | 🟠 MajorDuplicate endpoint documentation confirmed across multiple HTTP methods.
Both
patch-databases-id.mdxandpatch-databases-by-database-id.mdxdocument the identical endpointPATCH /v1/databases/{databaseId}with the same content, creating user confusion and maintenance overhead. Looking at the directory, this pattern repeats systematically:delete-databases-id.mdx/delete-databases-by-database-id.mdx,get-databases-id.mdx/get-databases-by-database-id.mdx, and so on. This suggests the generation script is producing both filename conventions for the same endpoints. Either the old naming scheme should be removed during generation, or if the intent was deliberate (e.g., migration), one set of files must be deleted to maintain a single source of truth.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/content/docs/management-api/endpoints/databases/patch-databases-id.mdx` around lines 1 - 21, The docs generator is producing duplicate endpoint files (e.g., patch-databases-id.mdx and patch-databases-by-database-id.mdx) causing duplicated docs for the same path; update the generation logic to emit only one canonical filename pattern (choose either the "-id.mdx" or "-by-database-id.mdx" convention) and remove the alternate duplicates during generation, ensuring the generator code that builds filenames (the routine that maps endpoint path/operation to output filename) normalizes path variables consistently and only writes the single chosen file for symbols like patch-databases-id.mdx, delete-databases-id.mdx, get-databases-id.mdx, etc.; if migration is needed, optionally add a cleanup step to delete the obsolete files after generation so only the canonical files remain.
🧹 Nitpick comments (1)
apps/docs/content/docs/management-api/endpoints/workspaces/get-workspaces-by-id.mdx (1)
2-2: Consider a more specific page title for disambiguation.Line 2 (
Get workspace) is a bit generic;Get workspace by IDwould better distinguish it from list/read-all pages in nav and search.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/content/docs/management-api/endpoints/workspaces/get-workspaces-by-id.mdx` at line 2, The page title "Get workspace" is too generic; update the frontmatter/title in the file (currently "title: Get workspace") to a more specific label such as "Get workspace by ID" so it disambiguates this endpoint from list/read-all pages in navigation and search; ensure any top-level header or title field in get-workspaces-by-id.mdx is changed to the new string.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In
`@apps/docs/content/docs/management-api/endpoints/connections/delete-connections.mdx`:
- Around line 11-14: Two MDX pages (delete-connections.mdx and
delete-connections-by-id.mdx) both document the same operation DELETE
/v1/connections/{id}, causing duplicate canonical URLs; fix by deduplicating at
generation or removing one output. Update the Fumadocs generation logic to key
pages by operation identity (e.g., method+path or operationId) and emit a single
MDX file (preferably keep delete-connections.mdx) or canonicalize URLs
consistently; alternatively delete the redundant delete-connections-by-id.mdx
and ensure the generator uses a deterministic slug rule (operationId or
normalized path+method) so future runs don’t recreate the duplicate.
In
`@apps/docs/content/docs/management-api/endpoints/database-backups/get-databases-by-database-id-backups.mdx`:
- Around line 4-12: The frontmatter currently nests the endpoint "path" under
"_openapi" (the key "path" inside the _openapi block); update the
generator/template so "path" is emitted as a top-level frontmatter key instead
of under "_openapi" (remove "path" from inside _openapi and render it alongside
_openapi at the root), ensure the rest of _openapi.structuredData and url remain
unchanged, and regenerate the file so generated pages (e.g., the file containing
_openapi and path) have "path" at top-level for correct metadata indexing.
In
`@apps/docs/content/docs/management-api/endpoints/databases-connections/get-databases-id-connections.mdx`:
- Line 12: This PR introduces a duplicate page for the same GET
/v1/databases/{databaseId}/connections operation; remove the legacy slug entry
(the line "url:
/management-api/endpoints/databases-connections/get-databases-id-connections" in
apps/docs/content/docs/management-api/endpoints/databases-connections/get-databases-id-connections.mdx)
or delete the entire legacy MDX file so only the canonical page remains, and if
backward compatibility is needed add a redirect from the legacy path to the
canonical page via your docs router/redirect config rather than keeping two
pages for the same operation.
In
`@apps/docs/content/docs/management-api/endpoints/databases-connections/post-databases-id-connections.mdx`:
- Line 12: This file contains a legacy slug "url:
/management-api/endpoints/databases-connections/post-databases-id-connections"
that duplicates the POST /v1/databases/{databaseId}/connections endpoint
documented elsewhere; remove the legacy slug/this duplicate page and retain the
canonical document that describes POST /v1/databases/{databaseId}/connections
(or replace this file with a proper redirect entry only if backward
compatibility requires it) so there is a single canonical page for that
endpoint.
In
`@apps/docs/content/docs/management-api/endpoints/databases/delete-databases-id.mdx`:
- Line 12: Remove the duplicate documentation by deleting or consolidating
apps/docs/content/docs/management-api/endpoints/databases/delete-databases-id.mdx
and keeping the canonical
apps/docs/content/docs/management-api/endpoints/databases/delete-databases-by-database-id.mdx
(or vice versa); then update the Fumadocs generation logic to deduplicate by
endpoint path (e.g., the DELETE /v1/databases/{databaseId} route) so it emits a
single filename per endpoint, or add a mapping rule that normalizes names (e.g.,
strip “-by-” variants) before writing files; ensure any internal links or
sidebars are updated to point to the retained file.
In
`@apps/docs/content/docs/management-api/endpoints/integrations/delete-integrations-by-id.mdx`:
- Around line 4-11: The frontmatter currently nests endpoint identity under
_openapi (fields "method" and "path"); move "method: DELETE" and "path:
'/v1/integrations/{id}'" out of the _openapi block into top-level frontmatter so
the metadata pipeline can detect the endpoint, leaving _openapi only for
doc-structure fields, and update the generator that emits this file to produce
method and path at top-level instead of nested under _openapi.
In `@apps/docs/content/docs/management-api/endpoints/projects/patch-projects.mdx`:
- Around line 11-14: This page duplicates the same API operation documented in
apps/docs/content/docs/management-api/endpoints/projects/patch-projects-by-id.mdx
(PATCH /v1/projects/{id}); remove the duplicate page or convert it into a
canonical/redirecting page: either delete
apps/docs/content/docs/management-api/endpoints/projects/patch-projects.mdx and
update any links to point to patch-projects-by-id.mdx, or add explicit
canonical/redirect frontmatter/meta in patch-projects.mdx that points to
patch-projects-by-id.mdx (and include the PATCH /v1/projects/{id} path in the
frontmatter) so only one canonical URL remains.
In
`@apps/docs/content/docs/management-api/endpoints/workspaces/get-workspaces-by-id.mdx`:
- Line 5: The frontmatter for this endpoint has inconsistent HTTP method casing
(the `_openapi.method` value is "GET" on one line and "get" elsewhere) which can
break case-sensitive metadata consumers; update the MDX frontmatter so the
`method` value uses the project standard (make both `_openapi.method` entries
the same case—prefer lowercased "get" to match other docs) or, alternatively,
update the parser that reads `_openapi.method` (the OpenAPI/frontmatter parsing
logic) to call toLowerCase() on the method before matching operations so casing
is normalized; locate the `_openapi.method` frontmatter in this file and fix it
or normalize in the parser function that handles frontmatter/operations.
In
`@apps/docs/content/docs/management-api/endpoints/workspaces/get-workspaces.mdx`:
- Line 2: Update the page title and metaTitle strings to use more natural
phrasing: change the frontmatter/title value "Get list of workspaces" to "Get a
list of workspaces" and likewise update any metaTitle fields (e.g., metaTitle)
that currently say "Get list of workspaces" to "Get a list of workspaces" so
both the visible title and SEO metaTitle match the smoother grammar.
In `@apps/docs/scripts/generate-docs.ts`:
- Around line 83-109: The code only checks types for data.url, data.metaTitle,
and data.metaDescription so stale/incorrect string values persist; update the
logic in generate-docs.ts to compare the existing values against the computed
ones and set data.url = url, data.metaTitle = metaTitle, and
data.metaDescription = metaDescription whenever they differ (not just when the
type is not a string), and set changed = true on overwrite; specifically adjust
the checks around the variables data.url, title/metaTitle (computed from
operation.method, operation.path and title), and description/metaDescription to
perform value inequality checks before assigning.
In `@apps/docs/src/app/og/`[...slug]/route.tsx:
- Around line 206-207: Replace the unsafe casts to any by adding a proper type
for the page frontmatter shape and using it when reading _openapi; specifically
define an interface (e.g., OpenApiMeta { method?: string; path?: string }) or
extend the existing Page type so you can access (page.data as { _openapi?:
OpenApiMeta })._openapi.method and .path without using any, then update the two
reads for method and apiPath to use that typed shape (referencing page.data,
_openapi, method, apiPath) so TypeScript will catch schema drift at compile
time.
---
Outside diff comments:
In
`@apps/docs/content/docs/management-api/endpoints/databases/patch-databases-id.mdx`:
- Around line 1-21: The docs generator is producing duplicate endpoint files
(e.g., patch-databases-id.mdx and patch-databases-by-database-id.mdx) causing
duplicated docs for the same path; update the generation logic to emit only one
canonical filename pattern (choose either the "-id.mdx" or "-by-database-id.mdx"
convention) and remove the alternate duplicates during generation, ensuring the
generator code that builds filenames (the routine that maps endpoint
path/operation to output filename) normalizes path variables consistently and
only writes the single chosen file for symbols like patch-databases-id.mdx,
delete-databases-id.mdx, get-databases-id.mdx, etc.; if migration is needed,
optionally add a cleanup step to delete the obsolete files after generation so
only the canonical files remain.
In `@apps/docs/src/app/og/`[...slug]/route.tsx:
- Around line 38-53: Normalize and validate the HTTP method before using it to
pick a color: convert the incoming method to a canonical form (e.g.,
methodNormalized = method?.toUpperCase()) and only set methodColor from
HTTP_METHOD_COLORS if HTTP_METHOD_COLORS hasOwnProperty(methodNormalized);
otherwise set methodColor to null so unsupported/typo values don't render a
badge. Update the code that computes methodColor and any other badge rendering
sites (the other occurrence using method/HTTP_METHOD_COLORS) to use
methodNormalized and the explicit presence check rather than relying on the
fallback color.
---
Nitpick comments:
In
`@apps/docs/content/docs/management-api/endpoints/workspaces/get-workspaces-by-id.mdx`:
- Line 2: The page title "Get workspace" is too generic; update the
frontmatter/title in the file (currently "title: Get workspace") to a more
specific label such as "Get workspace by ID" so it disambiguates this endpoint
from list/read-all pages in navigation and search; ensure any top-level header
or title field in get-workspaces-by-id.mdx is changed to the new string.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 5cef2bf8-6783-49a1-a5dd-7cc24d990fbe
📒 Files selected for processing (49)
apps/docs/content/docs/management-api/endpoints/connections/delete-connections-by-id.mdxapps/docs/content/docs/management-api/endpoints/connections/delete-connections.mdxapps/docs/content/docs/management-api/endpoints/connections/get-connections-by-id.mdxapps/docs/content/docs/management-api/endpoints/connections/get-connections.mdxapps/docs/content/docs/management-api/endpoints/connections/post-connections.mdxapps/docs/content/docs/management-api/endpoints/database-backups/get-databases-by-database-id-backups.mdxapps/docs/content/docs/management-api/endpoints/database-backups/get-databases-id-backups.mdxapps/docs/content/docs/management-api/endpoints/database-usage/get-databases-by-database-id-usage.mdxapps/docs/content/docs/management-api/endpoints/database-usage/get-databases-id-usage.mdxapps/docs/content/docs/management-api/endpoints/databases-connections/get-databases-by-database-id-connections.mdxapps/docs/content/docs/management-api/endpoints/databases-connections/get-databases-id-connections.mdxapps/docs/content/docs/management-api/endpoints/databases-connections/post-databases-by-database-id-connections.mdxapps/docs/content/docs/management-api/endpoints/databases-connections/post-databases-id-connections.mdxapps/docs/content/docs/management-api/endpoints/databases/delete-databases-by-database-id.mdxapps/docs/content/docs/management-api/endpoints/databases/delete-databases-id.mdxapps/docs/content/docs/management-api/endpoints/databases/get-databases-by-database-id.mdxapps/docs/content/docs/management-api/endpoints/databases/get-databases-id.mdxapps/docs/content/docs/management-api/endpoints/databases/get-databases.mdxapps/docs/content/docs/management-api/endpoints/databases/get-projects-by-project-id-databases.mdxapps/docs/content/docs/management-api/endpoints/databases/get-projects-id-databases.mdxapps/docs/content/docs/management-api/endpoints/databases/patch-databases-by-database-id.mdxapps/docs/content/docs/management-api/endpoints/databases/patch-databases-id.mdxapps/docs/content/docs/management-api/endpoints/databases/post-databases.mdxapps/docs/content/docs/management-api/endpoints/databases/post-projects-by-project-id-databases.mdxapps/docs/content/docs/management-api/endpoints/databases/post-projects-id-databases.mdxapps/docs/content/docs/management-api/endpoints/integrations/delete-integrations-by-id.mdxapps/docs/content/docs/management-api/endpoints/integrations/delete-integrations.mdxapps/docs/content/docs/management-api/endpoints/integrations/delete-workspaces-by-workspace-id-integrations-by-client-id.mdxapps/docs/content/docs/management-api/endpoints/integrations/delete-workspaces-id-integrations-id.mdxapps/docs/content/docs/management-api/endpoints/integrations/get-integrations-by-id.mdxapps/docs/content/docs/management-api/endpoints/integrations/get-integrations.mdxapps/docs/content/docs/management-api/endpoints/integrations/get-workspaces-by-workspace-id-integrations.mdxapps/docs/content/docs/management-api/endpoints/integrations/get-workspaces-id-integrations.mdxapps/docs/content/docs/management-api/endpoints/misc/get-regions-accelerate.mdxapps/docs/content/docs/management-api/endpoints/misc/get-regions-postgres.mdxapps/docs/content/docs/management-api/endpoints/projects/delete-projects-by-id.mdxapps/docs/content/docs/management-api/endpoints/projects/delete-projects.mdxapps/docs/content/docs/management-api/endpoints/projects/get-projects-by-id.mdxapps/docs/content/docs/management-api/endpoints/projects/get-projects.mdxapps/docs/content/docs/management-api/endpoints/projects/patch-projects-by-id.mdxapps/docs/content/docs/management-api/endpoints/projects/patch-projects.mdxapps/docs/content/docs/management-api/endpoints/projects/post-projects-by-id-transfer.mdxapps/docs/content/docs/management-api/endpoints/projects/post-projects-transfer.mdxapps/docs/content/docs/management-api/endpoints/projects/post-projects.mdxapps/docs/content/docs/management-api/endpoints/regions/get-regions.mdxapps/docs/content/docs/management-api/endpoints/workspaces/get-workspaces-by-id.mdxapps/docs/content/docs/management-api/endpoints/workspaces/get-workspaces.mdxapps/docs/scripts/generate-docs.tsapps/docs/src/app/og/[...slug]/route.tsx
apps/docs/content/docs/management-api/endpoints/connections/delete-connections.mdx
Outdated
Show resolved
Hide resolved
...tent/docs/management-api/endpoints/database-backups/get-databases-by-database-id-backups.mdx
Show resolved
Hide resolved
...content/docs/management-api/endpoints/databases-connections/get-databases-id-connections.mdx
Outdated
Show resolved
Hide resolved
...ontent/docs/management-api/endpoints/databases-connections/post-databases-id-connections.mdx
Outdated
Show resolved
Hide resolved
apps/docs/content/docs/management-api/endpoints/databases/delete-databases-id.mdx
Outdated
Show resolved
Hide resolved
apps/docs/content/docs/management-api/endpoints/projects/patch-projects.mdx
Outdated
Show resolved
Hide resolved
apps/docs/content/docs/management-api/endpoints/workspaces/get-workspaces-by-id.mdx
Show resolved
Hide resolved
apps/docs/content/docs/management-api/endpoints/workspaces/get-workspaces.mdx
Show resolved
Hide resolved
|
The latest updates on your projects. Learn more about Argos notifications ↗︎
|
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
.github/workflows/sync-management-api-docs.yml (1)
34-40: Remove duplicate OpenAPI fetch in workflow.
generate:management-api-docsalready runsfetch-openapi, so Lines 34–37 do the same fetch twice.♻️ Proposed workflow simplification
- - name: Fetch OpenAPI spec - working-directory: apps/docs - run: pnpm fetch-openapi - - name: Generate docs working-directory: apps/docs run: pnpm run generate:management-api-docs🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/workflows/sync-management-api-docs.yml around lines 34 - 40, Remove the redundant "Fetch OpenAPI spec" job step since the npm script generate:management-api-docs already runs fetch-openapi; delete the step with name "Fetch OpenAPI spec" (the working-directory apps/docs run: pnpm fetch-openapi) so only the "Generate docs" step that runs pnpm run generate:management-api-docs remains, avoiding duplicate fetches in the workflow.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In @.github/workflows/sync-management-api-docs.yml:
- Around line 34-40: Remove the redundant "Fetch OpenAPI spec" job step since
the npm script generate:management-api-docs already runs fetch-openapi; delete
the step with name "Fetch OpenAPI spec" (the working-directory apps/docs run:
pnpm fetch-openapi) so only the "Generate docs" step that runs pnpm run
generate:management-api-docs remains, avoiding duplicate fetches in the
workflow.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 81b3d624-9e58-4f18-b534-3d1c44702553
📒 Files selected for processing (10)
.github/workflows/sync-management-api-docs.ymlapps/docs/content/docs/management-api/endpoints/databases-connections/delete-connections.mdxapps/docs/content/docs/management-api/endpoints/databases-connections/meta.jsonapps/docs/content/docs/management-api/endpoints/databases/meta.jsonapps/docs/content/docs/management-api/endpoints/integrations/meta.jsonapps/docs/content/docs/management-api/endpoints/projects/meta.jsonapps/docs/package.jsonapps/docs/scripts/generate-docs.tsapps/docs/src/app/og/[...slug]/route.tsxpackage.json
💤 Files with no reviewable changes (1)
- apps/docs/content/docs/management-api/endpoints/databases-connections/delete-connections.mdx
aidankmcalister
requested review from
AmanVarshney01,
ankur-arch,
mhartington and
mhessdev
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit