Examples rendering for 'multipart/form-data' and 'application/x-www-form-urlencoded'

[v50553490-cyber]

Description

• Added posibility to render examples with tabs for 'multipart/form-data' and 'application/x-www-form-urlencoded'.

Motivation and Context

The commit makes it possible to render named or unnamed examples using SchemaTabs for 'multipart/form-data' + 'application/x-www-form-urlencoded'.

How Has This Been Tested?

• Locally with my own .yaml files.
• Checked all demos for issues.
• yarn test

Screenshots (if appropriate)

Types of changes

• New feature (non-breaking change which adds functionality)

Checklist

• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes if appropriate.
• All new and existing tests passed.

[sserrata]

PR Review — "Examples rendering for multipart/form-data"

Overall: The feature direction is good and aligns with how JSON/XML examples already work. However, there are a few bugs and design concerns to address before merging.

---

FileArrayFormBodyItem/index.tsx — Cleanup

Positive. The removal of the maxIndex variable is correct — it was computed but never used (newItems.set(index, ...) uses the index parameter directly). This is a clean dead-code removal.

---

FormBodyItem/index.tsx — Issues

1. Bug: Empty useEffect dependency array will cause ESLint violations

useEffect(() => {
  if (value) {
    dispatch(setStringFormBody({ key: id, value }));
  } else {
    dispatch(clearFormBodyKey(id));
  }
}, []); // ← missing deps: dispatch, id, value

The empty [] is intentional (fire once on mount), but react-hooks/exhaustive-deps will flag this. It needs a // eslint-disable-next-line react-hooks/exhaustive-deps comment to be consistent with the rest of the codebase (e.g., Body/index.tsx:283).

2. Behavioral change: object fields without examples now always get a LiveApp

// Before
if (schemaObject.type === "object" && (schemaObject.example || schemaObject.examples)) { ... }

// After (PR)
if (schemaObject.type === "object") { ... }

Objects without any example will now render an empty LiveApp editor instead of falling through to FormTextInput. This may be intentional, but it's an undocumented behavioral change that also affects application/x-www-form-urlencoded.

---

Body/index.tsx — Issues

3. Bug: example.value[schemaKey] is incorrect

// Single example tab (wrong)
exampleValue={example.value[schemaKey]}

// examples entries (correct — ExampleObject has .value)
exampleValue={value.value[schemaKey]}

Per the OpenAPI 3.x spec:

• content[type].example is a raw value (e.g., { field1: "foo" })
• content[type].examples maps to ExampleObjects which have a .value property

So example.value[schemaKey] incorrectly treats example as an ExampleObject. This should be example[schemaKey].

4. Design concern: Redux state contamination across tabs

SchemaTabs uses lazy, so each tab's FormBodyItems mount once (first activation) and stay mounted. Each FormBodyItem dispatches its exampleValue on mount via useEffect. This means:

1. User activates "Example (from schema)" tab → Redux set to schema defaults
2. User activates "Example" tab → Redux overwritten with example values
3. User switches back to "Example (from schema)" tab → Redux still holds "Example" values

The form body submitted would reflect the last-activated tab's values, not the currently visible tab. There's no mechanism to re-sync Redux when a tab becomes active after initial mount. Consider dispatching on tab activation rather than component mount.

5. Scope: application/x-www-form-urlencoded is also affected

The modified if block covers both content types:

if (
  (contentType === "multipart/form-data" ||
    contentType === "application/x-www-form-urlencoded") &&
  schema?.type === "object"
) {

The PR description only mentions multipart/form-data, but application/x-www-form-urlencoded is equally affected. Worth confirming this is intentional and testing both.

---

Summary

#	Severity	Issue
3	Bug	example.value[schemaKey] should be example[schemaKey]
4	Design	Tab switching doesn't re-sync Redux state (last-mounted tab wins)
1	Minor	useEffect([]) missing eslint-disable comment
2	Minor	Object fields without examples now always render LiveApp (undocumented change)
5	Informational	application/x-www-form-urlencoded is also affected, not just multipart/form-data

The dead-code removal in FileArrayFormBodyItem is a nice cleanup. Items 3 and 4 should be resolved before merging.

[v50553490-cyber]

Hi @sserrata, could you please re-check point 4 regarding design and Redux synchronization? I see that the useEffect part is called every time a tab is selected, so sync is applied.

Here is a screen recording:
https://github.com/user-attachments/assets/3bf92d55-117a-47e1-a8c9-4c21021c41b5

I agree with the rest comments.

[v50553490-cyber]

Fixed points 1 and 3.

Comments on other:
2. Yes, that should have been mentioned. I think it's more convenient to write objects in the LiveApp.
5. application/x-www-form-urlencoded has also been tested and works correctly.

[sserrata]

Thanks @v50553490-cyber, my apologies for the long delay in responding...everything looks good except for the following:

value.value[schemaKey] is missing a null guard

  // examples entries                                                                                                                    
  exampleValue={value.value[schemaKey]} 

If an ExampleObject has no value property (it's optional per the OpenAPI spec), this will throw at runtime. Can add a guard like this:

  exampleValue={value.value?.[schemaKey]}  

Same for example[schemaKey] on the single-example tab — safe since example is a raw object, but schemaKey may not exist in it. Returning undefined is fine there (since controlled inputs handle it), so that one is lower priority, but we should add the safety check for uniformity.

[github-actions]

Visit the preview URL for this PR (updated for commit fa2dc6a):

https://docusaurus-openapi-36b86--pr1315-wpyjbe90.web.app

_{(expires Wed, 29 Apr 2026 16:28:45 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: bf293780ee827f578864d92193b8c2866acd459f}

[v50553490-cyber]

Hi @sserrata, I've added a null guard for the exampleValue={value.value?.[schemaKey]} .
I do not really understand what type of check should be added for example[schemaKey], It's acceptable for it to be undefined, just like for value.value?. <FormBodyItem/> is designed to handle it correctly.

[sserrata]

Thanks @v50553490-cyber — the null guard for value.value?.[schemaKey] is in. For example[schemaKey] on the single-example tab, you're right that FormBodyItem handles undefined correctly and example is already guarded by the {example && ...} condition, so no additional check is needed there.

All items addressed — merging now.