[mehnoorsiddiqui]

Summary

Upgrades fumadocs-openapi from 12.1.1 to 12.4.1 for two fixes we reported upstream. The upgrade also brings Fumadocs' redesign of the API reference pages.

Issue	Fixed in	What changes in a portal
fuma-nama/fumadocs#3663	fumadocs-openapi 12.4.0	The playground's OAuth panel shows the redirect_uri it sends, with a copy button. It includes the portal's base path
fuma-nama/fumadocs#3661	fumadocs-openapi 12.4.0	Nothing visible. ApiMarkdown already kept a description image from crashing the page. It stays, because Fumadocs still doesn't add the base path to the image

This PR leaves out the image fix for the Markdown copies (#3662), which comes from fumadocs-core and fumadocs-mdx. Those stay at 16.15.17 and 15.4.0 here. fumadocs-openapi 12.4.1 accepts core and ui ^16.15.0.

The API page redesign (fumadocs-openapi 12.2 to 12.4)

• 12.2.0: The playground moves into a dialog that opens from a Try in Playground button. Until the button is clicked, the page has no <form>. The dialog is rendered in a portal, outside the page's article.
• 12.3.0: The schema UI moves into cards. Responses become tabs, callbacks open in dialogs, parameters sit in cards, and enum values show as tags.
• 12.4.0: Adds auth providers. cURL samples now quote with '.

QA: portal automation tests need updating before merge

cc @WasifIsrar @razazarif

The portal tests in apimatic/v4-test-automation were written against the old inline playground. Most of the auth functional tests and one visual baseline will fail against this build. portal_tests.yml runs only on pushes to dev, so this PR's checks don't show the failures. They would first appear after the merge.

What changed in the markup (fumadocs-openapi 12.4.1)

• The playground is a dialog. It opens from a Try in Playground button next to the endpoint bar. It's a Base UI Dialog, rendered in a portal outside #nd-page. Its title is the operation's title.
• The <form> now holds only the URL bar (method, path, Send). The request sections and the response are separate panels beside it, both still inside the dialog:
  • The request panel has Path, Query, Header, Cookies, Body and Authorization.
  • The response panel shows "Send a request to see its response." until a request is sent.
  • Below the md breakpoint, a Request / Response switch shows one panel at a time.
• OAuth is an inline panel inside Authorization. It has Client ID, Client Secret, Scopes, the "Send as Basic Auth header" / "Send client credentials in body" choice, a new Redirect URI field with a copy button, and an Authorize button. The test's separate "Authorization" dialog with a Submit button is gone.
• The endpoint page itself now uses cards for parameters and schemas, tabs for responses, and tags for enum values.

What needs updating

• pages/ApiReferencePage.ts
  • Click Try in Playground in open(), or add a step that does.
  • Scope playground to the dialog (page.getByRole("dialog")) instead of pageContent.locator("form"). Then re-check sendButton, responseStatus, responseBody, authorizationToggle, authSchemeSelect, parameterField(), authField() and openSection().
  • Rework oauthDialog, oauthSubmitButton and authorizeWithOAuth() for the inline OAuth panel.
• tests/functional/auth/auth.functional.test.ts: check each test still passes, and decide whether to assert on the new Redirect URI field. It should include the portal's base path.
• Re-capture the functional screenshots in portal-snapshots/functional/auth/. They show the playground's layout, which has changed.
• Re-capture portal-snapshots/visual/petstore/api-add-pet.png.
• Run the suite against this branch: gh workflow run portal_tests.yml --ref fix/portal-fumadocs-openapi-12.4. Its playwright-report and the diff PNGs show what moved.

The other visual tests and the artifact tests shouldn't change, because this PR only touches the API reference pages.

This PR stays a draft until the test changes are ready to merge alongside it.

Changes

• fumadocs-openapi 12.1.1 → 12.4.1.
• shiki 4.4.3 → 4.5.0 and lucide-react 1.47.0 → 1.54.0: the versions fumadocs-openapi 12.4 requires (^4.5.0, ^1.50.0), so each has a single copy.
• pnpm dedupe also merged two other duplicate copies:
  • @semantic-release/github's undici goes from 7.27.0 to 7.29.1. The next release run will use it.
  • micromark-util-types goes from 2.0.2 to 2.0.3.
• request-examples.ts and its test type a parameter as OperationParameter, which Fumadocs passes. ParameterObject.name is now optional.
• ApiMarkdown's doc comment and the e2e comment now say why it stays: for the base path, not the crash.
• .ai/plans/portal-subpath-hosting.md records #3661 and #3663 as fixed (5.10 and the upstream table).

Release age: fumadocs-openapi 12.4.1 was published on 2026-10-09, 10 days ago. That clears the 7-day minimumReleaseAge.

Test results

Full suite with e2e builds (APIMATIC_E2E=1 pnpm test): 1921 passing, 0 failing. ESLint clean.

In the browser: I built a portal from the subpath fixture plus an OAuth2 authorization-code scheme, served it under /api/, and drove it with headless Chrome.

Check	Result
Operation page with an image in its description	Renders. The image loads from /api/images/diagram.png. No console errors
Try in Playground	Opens the dialog with the form, Send, the auth section and the cURL sample
OAuth panel	Shows redirect_uri: http://127.0.0.1:4719/api/oauth/callback with a copy button. Authorize sent the same value (redirect_uri=http%3A%2F%2F127.0.0.1%3A4719%2Fapi%2Foauth%2Fcallback)

Related

#437 upgrades all four Fumadocs packages. Once this PR merges, #437 can drop fumadocs-openapi and keep the image fix alone (core and ui 16.17, mdx 15.4.7).

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud