swagger-api / swagger-api/swagger-ui
OpenAPI 3.1.0 support: OpenAPI 3.1 type: […, "null"] incomplete support in parameters
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 29k
- Forks
- 9.3k
- Avg merge
- 2d 23h
- Merged PRs (30d)
- 25
Description
Q&A (please complete the following information)
- OS: Ubuntu
- Browser: Firefox
- Version: 114.0.2
- Method of installation: apt
- Swagger-UI version: https://editor-next.swagger.io/
- Swagger/OpenAPI version: 3.1
Content & configuration
Example Swagger/OpenAPI definition:
https://gist.github.com/commonism/7adcb666278f4070b8f7aabd456faa43
openapi: 3.1.0
info:
title: ''
version: 0.0.0
servers:
- url: http://127.0.0.1/api
security:
- {}
paths:
/{path}:
parameters:
- $ref: "#/components/parameters/path"
- $ref: '#/components/parameters/cookie'
post:
operationId: post
requestBody:
description: "!"
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Any'
responses:
'200':
description: "!"
content:
application/json:
schema:
$ref: "#/components/schemas/Any"
callbacks:
onData:
'{$request.query.callbackUrl}/data':
post:
requestBody:
description: "!"
content:
application/json:
schema:
$ref: "#/components/schemas/Any"
responses:
'200':
description: "!"
content:
application/json:
schema:
$ref: "#/components/schemas/Any"
get:
operationId: get
parameters:
- $ref: "#/components/parameters/query"
- $ref: "#/components/parameters/header"
responses: &resp
'200':
description: "!"
content:
application/json:
schema:
$ref: '#/components/schemas/Any'
headers:
head:
$ref: "#/components/headers/header"
components:
schemas:
Any:
type: [integer, string, object, array, boolean, "null"]
items:
$ref: "#/components/schemas/Any"
properties:
next:
$ref: "#/components/schemas/Any"
headers:
header:
schema:
$ref: "#/components/schemas/Any"
style: simple
explode: false
parameters:
query:
in: query
name: query
style: deepObject
explode: true
required: true
schema:
$ref: "#/components/schemas/Any"
path:
in: path
name: path
required: true
schema:
type: [string, "null"]
header:
in: header
name: header
required: true
schema:
type: [string, "null"]
cookie:
in: cookie
name: cookie
required: true
schema:
type: [string, "null"]
Describe the bug you're encountering
The rendering of the parameters does not reflect the use of OpenAPI 3.1 type as a list.
The use of "null" as list element to indicate "nullable" is not reflected as well.
To reproduce...
Steps to reproduce the behavior:
Paste the yaml to swagger editor.
Expected behavior
Screenshots
Bad types for Response & header
all Parameters
Callback Response
but works for a RequestBody
Additional context or thoughts
type: […, "null"] is the preferable way to define nullable in v3.1, using the alternative anyOf: […,{type: "null"}] instead results in a additional/unnecessary level of indirection in models generated from description documents.
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 pasting the provided YAML into Swagger Editor and trace how schema types are rendered for parameters, headers, responses, and callbacks. Compare those paths with the request-body rendering, then verify that OpenAPI 3.1 type arrays containing "null" display correctly in each affected location without regressing request-body behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, openapi
- Domain
- documentation, frontend
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100