Nullable support in `oneOf` operator
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 25.9k
- Forks
- 2.4k
- Avg merge
- 13h 10m
- Merged PRs (30d)
- 4
Description
This is feature request.
Currently, redoc@2.0.0-rc.30 can show nullable: true field(s) on properties like below:
This is great !!
I have API requests/responses that uses oneOf operator, and some of schemas used in oneOf is nullable: true like below:
Foo:
oneOf:
- $ref: "#/components/schemas/Foo1"
- $ref: "#/components/schemas/Foo2"
Foo1:
type: object
properties: ...
Foo2:
type: object
nullable: true
properties: ...
I think this is valid schema definition to express object could be null, according to OpenAPI 3.0 specs.
OpenAPI 3.0 does not have an explicit null type as in JSON Schema, but you can use nullable: true to specify that the value may be null.
https://swagger.io/docs/specification/data-models/data-types/#null
So, it would be great if ReDoc can render such objects as nullable.
UI Suggestions
Example OpenAPI file
Example OpenAPI.yaml
openapi: "3.0.0"
info:
version: "1.2.3"
title: "My API"
paths:
/foo:
post:
operationId: postFoo
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/Foo"
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Foo"
/bar:
post:
operationId: postBar
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/Foo2"
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Foo2"
components:
schemas:
Foo:
oneOf:
- $ref: "#/components/schemas/Foo1"
- $ref: "#/components/schemas/Foo2"
Foo1:
type: object
properties:
foo1:
type: string
nullable: true
bar:
type: object
nullable: true
properties:
x:
type: int
y:
type: int
Foo2:
type: object
nullable: true
properties:
bar:
type: string
nullable: true
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the behavior with the embedded Example OpenAPI.yaml, focusing on the Foo oneOf schema and its nullable Foo2 member. Trace how ReDoc renders nullable properties and oneOf schemas, then verify that the rendered documentation indicates the nullable option for the oneOf member.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, typescript
- Domain
- documentation, frontend
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100