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
examples
test 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
- false
Screenshots
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: