fix(portal): render a request body in a media type Fumadocs has no adapter for

[saeedjamshaid]

The bug

An operation whose request body is text/html, application/pdf, image/* or */* was published as the router's "Something went wrong! Show Error" screen, with no content, sidebar or navigation. portal generate still exited 0 and reported success. Reported in apimatic/apimatic-io#2236.

Cause

fumadocs-openapi throws Media type … is not supported while rendering a request body whose media type has no adapter (dist/ui/operation/index.js:108). It ships adapters only for JSON, XML, NDJSON, x-www-form-urlencoded, multipart/form-data and octet-stream, plus their +json/+xml variants. text/plain borrows the JSON adapter, but only when spelled exactly text/plain. The throw is still there in 12.0.4 and is intentional upstream (fuma-nama/fumadocs#1810). Its escape hatch is the mediaAdapters option, which the portal did not use.

The .md twins and llms-full.txt were never affected, because they print the YAML without going through Fumadocs.

The change

portal-template/src/lib/media-adapters.ts gives Fumadocs one adapter for a fixed list of the common types it lacks:

• the wildcards,
• the .NET/Swashbuckle defaults text/json and application/*+json, which fail the same way,
• the usual text, document and image types.

api-page.tsx passes the list to createOpenAPIPage.

The adapter sends a file or text as entered, and an object the playground built from the schema as JSON. Fumadocs' own octet-stream pass-through would send that object as [object Object].

text/plain is on the list too. Fumadocs' fallback compares the raw type string, so text/plain; charset=utf-8 crashed the page, and a bare text/plain body went out JSON-quoted ("string").

Fumadocs matches a wildcard only as written, so image/* does not cover image/webp. Any type the list does not name still fails the same way. That is the known limit of a fixed list: fumadocs builds its adapter map by spreading ours into it, so a catch-all cannot work. The alternative, a list built per page from the spec, is described on the issue.

Verifying it

• New e2e case: the branded fixture gains an image/* upload operation, and the test checks that its page renders the request-body section. It fails on dev and passes with the change.
• New unit tests: the adapter sends text and files as-is and objects as JSON, and every listed type is written the way Fumadocs looks it up (lowercase, without parameters).
• I built the spec attached to #2236, plus a spec with the Swashbuckle types, and loaded the pages in headless Chrome. All of them render after hydration with no errors.
• Clicking Send in the playground sends:
  • */*: {}
  • application/pdf: the raw text
  • text/plain: string, previously "string"
  • application/json: unchanged
• A spec using text/plain; charset=utf-8 and Text/HTML now builds with no render errors, and only image/webp still fails.
• pnpm test: 1432 passing. The portal-build e2e suite: 40 passing.

🤖 Generated with Claude Code

[saeedjamshaid]

Review note: does the new adapter drop the body from text/plain code samples?

The concern raised: fumadocs' language generators (JavaScript, Python, Go, Java, C#, Rust) build a sample's body line from the adapter's generateExample. On dev, text/plain fell through to the JSON adapter, which has one. The new adapter returns undefined, so a generated sample would lose its body.

The mechanism is right, but the portal never runs those generators, so no sample regresses:

• api-page.tsx passes an empty createCodeUsageGeneratorRegistry(). fumadocs registers its language generators only when codeUsages is omitted (registerDefault in dist/ui/base.js:29).
• renderAPIExampleUsageTabs is our UsageTabs: cURL, which bypasses adapters, plus the x-apimatic-codeSamples SDK samples.
• Both builds of the apimatic/apimatic-io#2236 spec, dev and this branch, show no fetch( sample on the text/plain page, and no bundle contains the JavaScript or Python generator. That's why the HTML diff is byte-identical.

So a real generateExample would be code nothing calls. 6822c5f adds a one-line comment on it saying so, which also flags that it needs one if fumadocs' generators are ever registered.

What does change for text/plain is the playground's Send: dev sent the text JSON-quoted ("hello"), and this branch sends it as written (hello).

[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

[github-actions]

🎉 This PR is included in version 2.0.0-beta.1 🎉

The release is available on:

• npm package (@beta dist-tag)
• GitHub release

Your semantic-release bot 📦🚀