feat: improve REST API reference scanability

[Jiayi-Ye02]

Summary

• introduce a shared OpenAPI field row and schema tree with request-aware disclosure, clearer nesting, consistent required/optional/deprecated badges, and quieter field anchors
• unify English response rendering by status code and add adaptive request example previews with line wrapping and a responsive sticky rail
• preserve response, reference, hash-target, and code-sample behavior with focused regression coverage

Verification

• bun run test src/styles/app-css-regressions.test.ts src/components/openapi/OpenApiFieldRow.test.tsx src/components/openapi/OpenApiSchemaTree.test.tsx src/components/openapi/FumadocsOpenApiContent.test.tsx src/components/openapi/OpenApiCodePreview.test.tsx src/components/openapi/OpenApiExamplesRail.test.tsx src/components/openapi/OpenApiResponses.test.tsx src/lib/openapi/anchors.test.ts src/lib/openapi/response-view.test.ts src/lib/openapi/schema-tree.test.ts
• bun run types:check
• bunx biome check on all 20 changed files
• visually verified the Conversational AI join page at desktop and 480px widths

[github-actions]

Vercel Preview

Preview URL: https://docs-portal-701emgk7s-agora-gdxe.vercel.app

[shczhen]

After visual review, we do not want to continue with the current custom schema UI direction as the final design.

The intended direction is to follow the current Fumadocs OpenAPI visual grammar and interaction model—information density, field semantics, nested-schema navigation, filtering, and responsive composition—while applying the Agora design system for color, typography, spacing, borders, radii, focus treatment, and dark mode.

There is valuable work in this PR that should be retained as implementation reference, especially the sticky examples rail, syntax highlighting, response organization, quieter anchors, locale-aware behavior, and regression coverage. However, the custom field renderer has diverged too far from Fumadocs and produces an overly heavy and long mobile experience. In the reviewed 480 px route, the page was approximately 10,203 px tall versus approximately 5,325 px on the current production page.

The replacement work and acceptance criteria are now tracked in #1041 so another contributor or agent can pick it up independently:

• prefer official Fumadocs components and supported composition seams;
• apply the Agora design system rather than copying Fumadocs branding;
• restore compact field rows, restrained required/optional semantics, property filtering, and Fumadocs-aligned nested-object interaction;
• preserve the useful rail, code-sample, response, localization, anchor, hash-target, and browser-find behavior demonstrated here;
• validate rendered results at desktop, tablet, and mobile widths in both light and dark mode.

Please treat this PR as implementation and test reference for #1041 rather than as the accepted final field-design direction. This comment does not close the PR or discard its reusable work.

[Jiayi-Ye02]

Implemented the Fumadocs-aligned schema direction in 2cf8d3f (with design context in 8e42347).

• Replaced the custom Schema Tree and Field Row renderer with the official Fumadocs Schema UI, including compact rows, * / ? requiredness, property filtering, and upstream nested-type navigation.
• Preserved the examples rail, syntax-highlighted examples, response-status organization, locale-aware labels, callouts, and response headers.
• Preserved existing request-field deep links: legacy #request-body-properties-* hashes now convert to the official path / s-highlight navigation state. The browser-find bridge also supports oneOf / anyOf branch selection.
• Verified the Conversational AI join route at 1440, 1280, 1200, and 480 px in light and dark mode. The 480 px route is 5,238 px with no document horizontal overflow; the examples rail is sticky at 1440/1280 and returns to normal flow at 1200/480.

Verification:

• Focused OpenAPI/CSS/DocsContent suite: 121 passing tests.
• Type check and changed-file Biome checks pass.
• Full production client and SSR bundles build successfully. The final static prerender stopped on an external fetch ECONNRESET, so the full bun run build command did not exit successfully.
• The repository-wide test and lint commands still have unrelated existing failures outside this change.

[shczhen]

Re-reviewed the final PR head (a4e268a4) against the Fumadocs-alignment direction in #1041 and the existing REST API behavior.

Rendered coverage included representative endpoints from Cloud Recording, Cloud Transcoding, Media Gateway, RTC, and Speech-to-Text, with desktop, 1200 px, and 480 px light/dark checks. I verified deep request/response schemas, property filters, field permalinks, endpoint copy, bounded code-sample scrolling, responsive rail behavior, and document-level overflow. I found no blocking UI or behavior regressions across that coverage.

Verification on the final head:

• focused OpenAPI/docs-shell suite: 168/168 passing;
• bun run types:check: passing;
• Vercel Preview deployment: passing.

The final implementation stays on the official Fumadocs SchemaUI, with narrow compatibility and styling patches for legacy hashes, browser find, accessible field links, responsive endpoint affordances, and Agora visual tokens. The small duplicated helper/record-guard implementations are non-blocking maintenance follow-ups rather than correctness issues.

One scope confirmation remains for @Jiayi-Ye02: commits 6d336084 (docs: reorder deprecated preset field) and 5ffbbc73 (docs: remove duplicate pipeline id description) were added after the review-direction comment and change the Conversational AI OpenAPI source rather than the renderer. Could you confirm that both content-only changes are intentional and should remain in this PR? If yes, I have no other blocking findings from this review.

[shczhen]

Follow-up review on the updated head (8d2fe4bc):

Nested object schemas now render recursively inline across request bodies, response bodies, and object-shaped parameters. Nested object, array<object>, and composition branches remain in the normal page DOM, so native browser search can find their fields without opening a popover. Recursive references stop at the cycle boundary, with regression coverage for finite rendering.

The implementation remains on the official Fumadocs SchemaUI, using a narrow nestedDisplay="inline" extension. Existing root property filters, required/optional syntax, field permalinks, legacy hash conversion, path highlighting, request/response organization, endpoint copy, and responsive examples-rail behavior are preserved.

Rendered verification covered the deep Conversational AI Join schema at 1440 px and 480 px, plus representative Cloud Recording, RTC, and Speech-to-Text REST endpoints. I found no document-level horizontal overflow, schema popovers, or object-type trigger buttons. The accepted tradeoff is page length: the Conversational AI route grows to approximately 41,873 px on desktop and 51,697 px on mobile because all nested fields are present and searchable.

Verification:

• focused OpenAPI/docs-shell suite: 169/169 passing;
• bun run types:check: passing;
• changed-file Biome check: passing;
• bun run build: passing, including 3,666 generated static route HTML files;
• final Standards review: 0 findings;
• final Spec review: 0 findings.

The repository-wide test run still reports unrelated pre-existing content-audit failures outside this renderer change. The new Vercel Preview checks are currently queued/in progress, not failed.

The earlier content-scope question remains open for @Jiayi-Ye02: please confirm whether 6d336084 and 5ffbbc73 are intentional content changes that should remain in this PR. Other than that confirmation and the running Preview checks, I found no blocking issues.

[shczhen]

Implemented the two merge-blocking follow-ups in bbd9690a2 (rebased onto the latest PR head):

• Native find now indexes dotted schema paths such as properties.llm.mcp_servers. A match raises beforematch, expands the complete ancestor chain, focuses/highlights the target row, and leaves unrelated branches collapsed.
• Required/Deprecated badges now use the existing semantic fd-error / fd-warning theme tokens instead of hard-coded red/orange palette classes.

Verification:

• Focused OpenAPI suite: 243/243 passed
• Post-rebase tree/field-row tests: 30/30 passed
• bun run types:check: passed
• Biome + git diff --check: passed
• bun run build: passed
• Browser checks at 1440px and 390px, light and dark: no horizontal overflow; semantic colors resolve correctly; dotted-path reveal expands, focuses, and highlights the intended field

The full bun run test suite remains non-green with 31 failures outside these changed files (content-audit/migration fixtures and analytics mocks). The mobile disclosure hit area remains a non-blocking follow-up as discussed.

From this review's scope, the two blockers are resolved and the PR is ready for merge once the current CI/deploy checks finish successfully.

[shczhen]

Approved. The dotted-path native find behavior and semantic status-color tokens are now addressed, and the focused tests, type checks, production build, and responsive browser verification are satisfactory.

[shczhen]

Re-reviewed the latest head (9d3ce4b38) against the previously approved fixed point (bbd9690a2), Issue #1041, and the new section-heading / status-metadata / metadata-value specs.

I found merge-blocking regressions in the new increment, so I am not approving this head yet:

1. Restore semantic status colors. OpenApiSchemaFieldRow.tsx has reintroduced raw red-* / orange-* Tailwind classes for Required and Deprecated. This reverses the fix already accepted at bbd9690a2, where these badges used the repository fd-error / fd-warning semantic tokens. Please restore the semantic classes and keep the regression test aligned with them.

2. Keep each section anchor ID unique. OpenApiResponses currently renders id="response-body" on both the outer <section> and the inner <h2>. I confirmed two matching elements in the deployed DOM. This makes fragment targeting and accessible ID resolution ambiguous. Keep the ID on exactly one element, consistent with the shared heading contract, and add a uniqueness assertion.

3. Reconcile the committed metadata contract with the implementation. The approved metadata-value design says values are blue, bold, and monospace, while the current CSS renders them amber/yellow at font-weight: 400. The newer specs also disagree about whether Optional and deprecated strike-through should be preserved. If the latest visual iteration is the intended product decision, please update/supersede the stale spec and plan language; otherwise restore the documented styling. The implementation and its checked-in review gates should describe one decision.

Verification on the exact head:

• desktop light and 390 px dark browser checks: no document-level horizontal overflow;
• duplicate response-body ID and current computed metadata/status styles reproduced in the deployed Preview;
• bun run types:check: passed;
• changed-file Biome check and git diff --check: passed;
• Vercel Preview: passed.

A focused test run reports 255/256 passing because the generated-language code-viewport assertion does not observe the effect-applied attribute in this local test environment. I reproduced the same failure at the previously approved fixed point, while the deployed DOM has the expected attribute, so I am not attributing that failure to this increment.

Once the three items above are resolved, I can re-review and approve.

[Jiayi-Ye02]

Resolved in a7fb19857, pushed to the PR head.

• Required and Deprecated badges now use the semantic fd-error / fd-warning tokens instead of raw red/orange palette classes.
• Removed the duplicate response-body ID from the outer responses wrapper; the section heading is now the only element with that anchor ID, with a uniqueness regression assertion.
• Kept the confirmed product decision for metadata values: current theme-token styling and regular weight; we did not switch back to blue/bold values. The metadata spec and plan were updated to describe this decision. Optional badges remain removed, and deprecated parameter names remain without strikethrough.

Verification:

• OpenAPI/CSS focused suite: 151/151 passing
• npm run types:check: passing
• Changed-file Biome check: passing
• Browser verification: one response-body ID, semantic status classes, no Optional badges, and no horizontal overflow at the join endpoint.