-
Notifications
You must be signed in to change notification settings - Fork 295
Description
Describe the bug
In OpenAPI Spec 3.1, examples were added to some objects for compatibility with JSON Schema.
https://swagger.io/specification/#example-object
However, this plugin doesn’t fully support that.
Specifically, the following request/response types are not supported.
- Request
1.1. Request Parameter: OK
1.2. Media Type Object: NO
1.3. Schema Object: NO
1.4. Schema Property Object: NO - Response
2.1. Media Type Object: OK
2.2. Schema Object: NO
2.3. Schema Property Object: NO
Expected behavior
The examples must be displayed correctly.
In particular, since example is deprecated in Schema Object and Schema Property Object, it’s important to support examples instead.
https://swagger.io/specification/#schema-object
Current behavior
I verified it using an examples test in the demo's test suite.
1.2. Media Type Object in Request Body: NO

1.3. Schema Object in Request Body: NO

1.4. Schema Property Object in Request Body: NO

2.2. Schema Object in Response Body: NO

2.3. Schema Property Object in Response Body: NO

Possible solution
For Response, the Media Type Object is already displayed correctly, so it should be shown in the same way.
For Request, however, the request body doesn’t have Schema and Example tabs like the response does. First, we should add Schema and Example tabs to the request body.
Then, we can support examples just like in the response.
What do you think? If you're okay with it, I’ll go ahead and create a few PRs.
Steps to reproduce
- Add the
examplestest cases for tests in the demo. - Build and start the server to check it.
examples test cases:
examples.yaml
openapi: 3.1.0
info:
title: Examples Demo API
description: Demonstrates various examples schema combinations.
version: 1.0.0
license:
name: MIT
url: https://opensource.org/licenses/MIT
security: []
servers:
- url: http://test.local:8080
description: Local server
tags:
- name: examples
description: examples
paths:
/requestParameters/example:
get:
tags:
- examples
summary: example in request parameters
parameters:
- name: name
description: name example
in: query
schema:
type: string
example: "John Doe"
- name: age
description: age example
in: query
schema:
type: number
example: 25
responses:
"204":
description: no content
/requestParameters/examples:
get:
tags:
- examples
summary: examples in request parameters
parameters:
- name: name
description: name example
in: query
schema:
type: string
examples:
example1:
summary: "name example 1"
description: "name example 1 description"
value: "John Doe"
example2:
summary: "name example 2"
description: "name example 2 description"
value: "Jane Doe"
responses:
"204":
description: no content
/requestParameters/schema/example:
get:
tags:
- examples
summary: example in request parameters schema
parameters:
- name: name
description: name example
in: query
schema:
type: string
example: "John Doe"
- name: age
description: age example
in: query
schema:
type: number
example: 25
responses:
"204":
description: no content
/requestParameters/schema/examples:
get:
tags:
- examples
summary: examples in request parameters schema
parameters:
- name: name
description: name example
in: query
schema:
type: string
examples:
- "John Doe"
- "Jane Smith"
- name: age
description: age example
in: query
schema:
type: number
examples:
- 25
- 30
responses:
"204":
description: no content
/requestBody/mediaTypeObject/example:
post:
tags:
- examples
summary: example of media type object in requestBody
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
age:
type: number
isStudent:
type: boolean
example:
name: "John Doe"
age: 25
isStudent: false
responses:
"204":
description: no content
/requestBody/mediaTypeObject/examples:
post:
tags:
- examples
summary: examples of media type object in requestBody
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
age:
type: number
isStudent:
type: boolean
examples:
example1:
value:
name: "John Doe"
age: 25
isStudent: false
example2:
value:
name: "Jane Smith"
age: 30
isStudent: true
responses:
"204":
description: no content
/requestBody/schema/example:
post:
tags:
- examples
summary: example of schema in requestBody
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
age:
type: number
isStudent:
type: boolean
example:
name: "John Doe"
age: 25
isStudent: false
responses:
"204":
description: no content
/requestBody/schema/examples:
post:
tags:
- examples
summary: examples of schema in requestBody
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
age:
type: number
isStudent:
type: boolean
examples:
- name: "John Doe"
age: 25
isStudent: false
- name: "Jane Smith"
age: 30
isStudent: true
responses:
"204":
description: no content
/requestBody/schema/properties/example:
post:
tags:
- examples
summary: example of properties in requestBody schema
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: "John Doe"
age:
type: number
example: 25
isStudent:
type: boolean
example: false
responses:
"204":
description: no content
/requestBody/schema/properties/examples:
post:
tags:
- examples
summary: examples of properties in requestBody schema
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
examples:
- "John Doe"
- "Jane Smith"
age:
type: number
examples:
- 25
- 30
isStudent:
type: boolean
examples:
- true
- false
responses:
"204":
description: no content
/response/mediaTypeObject/example:
get:
tags:
- examples
summary: example of media type object in response
responses:
"200":
description: successful response
content:
application/json:
schema:
type: object
properties:
name:
type: string
age:
type: number
isStudent:
type: boolean
example:
name: "John Doe"
age: 25
isStudent: false
/response/mediaTypeObject/examples:
get:
tags:
- examples
summary: examples of media type object in response
responses:
"200":
description: successful response
content:
application/json:
schema:
type: object
properties:
name:
type: string
age:
type: number
isStudent:
type: boolean
examples:
example1:
value:
name: "John Doe"
age: 25
isStudent: false
example2:
value:
name: "Jane Smith"
age: 30
isStudent: true
/response/schema/example:
get:
tags:
- examples
summary: example of schema in response
responses:
"200":
description: successful response
content:
application/json:
schema:
type: object
properties:
name:
type: string
age:
type: number
isStudent:
type: boolean
example:
name: "John Doe"
age: 25
isStudent: false
/response/schema/examples:
get:
tags:
- examples
summary: examples of schema in response
responses:
"200":
description: successful response
content:
application/json:
schema:
type: object
properties:
name:
type: string
age:
type: number
isStudent:
type: boolean
examples:
- name: "John Doe"
age: 25
isStudent: false
- name: "Jane Smith"
age: 30
isStudent: true
/response/schema/properties/example:
get:
tags:
- examples
summary: example of schema properties in response
responses:
"200":
description: successful response
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: "John Doe"
age:
type: number
example: 25
isStudent:
type: boolean
example: false
/response/schema/properties/examples:
get:
tags:
- examples
summary: examples of schema properties in response
responses:
"200":
description: successful response
content:
application/json:
schema:
type: object
properties:
name:
type: string
examples:
- "John Doe"
- "Jane Smith"
age:
type: number
examples:
- 25
- 30
isStudent:
type: boolean
examples:
- true
- falseScreenshots
Context
Your Environment
- Version used:
- Environment name and version (e.g. Chrome 59, node.js 5.4, python 3.7.3):
- Operating System and version (desktop or mobile):
- Link to your project:

