Skip to content

feat(oas32): render itemSchema of sequential media types - #11099

Open
SahinurDEV wants to merge 2 commits into
swagger-api:mainfrom
SahinurDEV:feat/oas32-item-schema
Open

SahinurDEV wants to merge 2 commits into
swagger-api:mainfrom
SahinurDEV:feat/oas32-item-schema

Conversation

@SahinurDEV

Copy link
Copy Markdown

Description

OpenAPI 3.2 lets a Media Type Object describe sequential media types (text/event-stream, application/jsonl, application/json-seq, multipart/mixed, …) with itemSchema instead of schema. Swagger UI only ever read schema, so for a response or request body that uses itemSchema the Example Value / Schema section was simply missing.

This adds a getMediaTypeSchemaField(mediaType) fn:

  • the oas3 plugin registers a default that always returns "schema", so OAS 3.0/3.1 behaviour is unchanged;
  • the oas32 plugin overrides it in afterLoad through wrapOAS32Fn (same pattern as isFileUploadIntended), returning "itemSchema" when the media type has itemSchema and no schema. If both are present schema still wins.

Response and RequestBody (plus getDefaultRequestBodyValue) use that field for the model, the generated example and the spec path (…/content/<type>/itemSchema), so $refs, model expansion and generated samples work like they do for schema. A small "Schema of each item in the <type> sequence" note is shown above the example/model so it's clear the sample is a single item, not the whole body. itemSchema request bodies are never rendered as form fields, since a multipart/mixed item schema describes each part rather than named fields.

I also moved itemSchema from the "not yet implemented" list to the implemented list in the oas32 plugin doc comment.

Motivation and Context

Fixes #11065

How Has This Been Tested?

  • Added test/unit/core/plugins/oas32/item-schema.test.jsx (8 tests): getMediaTypeSchemaField cases (only itemSchema, both fields, neither, Map and plain object), the afterLoad wrapper returning itemSchema only for OAS 3.2 documents, <Response> rendering the model/example/spec path from itemSchema with the note (and unchanged output for schema), getDefaultRequestBodyValue building the body from itemSchema, and <RequestBody> rendering a multipart/mixed itemSchema as a model instead of a form. 7 of them fail without the source changes.
  • npm run test:unit: 81 suites / 898 tests passed (12 skipped, same as before).
  • npm run lint-errors: clean.

Checklist

My PR contains...

  • No code changes (src/ is unmodified: changes to documentation, CI, metadata, etc.)
  • Dependency changes (any modification to dependencies in package.json)
  • Bug fixes (non-breaking change which fixes an issue)
  • Improvements (misc. changes to existing features)
  • Features (non-breaking change which adds functionality)

My changes...

  • are breaking changes to a public API (config options, System API, major UI change, etc).
  • are breaking changes to a private API (Redux, component props, utility functions, etc.).
  • are breaking changes to a developer API (npm script behavior changes, new dev system dependencies, etc).
  • are not breaking changes.

Documentation

  • My changes do not require a change to the project documentation.
  • My changes require a change to the project documentation.
  • If yes to above: I have updated the documentation accordingly.

Automated tests

  • My changes can not or do not need to be tested.
  • My changes can and should be tested by unit and/or integration tests.
  • If yes to above: I have added tests to cover my changes.
  • If yes to above: I have taken care to cover edge cases in my tests.
  • All new and existing tests passed.

SahinurDEV and others added 2 commits October 19, 2026 10:30
OpenAPI 3.2 Media Type Objects can describe sequential media types
(text/event-stream, application/jsonl, multipart/mixed, ...) with
itemSchema instead of schema. Responses and request bodies only read
schema, so these media types rendered without any example or model.

Add a getMediaTypeSchemaField fn that picks itemSchema for OAS 3.2 media
types that have no schema, and use it in Response and RequestBody for
the model, generated example and spec path. A short note marks the
schema as describing each item of the sequence, and itemSchema request
bodies are never rendered as form fields.

Fixes swagger-api#11065
… feat/oas32-item-schema

Signed-off-by: SahinurDEV <68515168+SahinurDEV@users.noreply.github.com>

# Conflicts:
#	src/core/components/response.jsx
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

itemSchema is not rendered for sequential media types (OpenAPI 3.2)

1 participant