openapi: 3.0.0
info:
title: Support for request body and parameter examples
description: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#requestBodyObject
version: 1.0.0
servers:
- url: https://httpbin.org/anything
tags:
- name: Multiple examples
- name: Single example
- name: Multiple media types
paths:
'/parameterExamples/{param1}/{param2}':
get:
tags:
- Multiple examples
summary: Within `examples` (parameters)
description: "This operation has several parameters with examples alongside
separately maintained example within `examples` at the Media Type Object level.\n\n\U0001F4DA
OpenAPI specification references:\n\n* [3.0.3 Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject)\n\n*
[3.1.0 Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)"
parameters:
- name: param1
in: path
required: true
schema:
type: string
examples:
userRegistration:
summary: example summary (param 1)
description: a lengthier example description (param 1)
value: param1-example
yetAnotherParamExample:
value: param1-example-again
- name: param2
in: path
required: true
schema:
type: string
examples:
userRegistration:
summary: example summary (param 2)
description: a lengthier example description (param 2)
value: param2-example
responses:
'200':
description: OK
content:
application/json:
schema:
'$ref': '#/components/schemas/user'
examples:
userRegistration:
value:
summary: example summary (response)
description: a lengthier example description (response)
id: 1234
email: test+response@example.com
name: Test user name (response)
response:
value:
id: 1234
email: test@example.com
name: Test user name
'400':
description: Validation failed
content:
application/xml:
examples:
response:
value: Invalid
user!
default:
description: OK
content:
application/json:
schema:
'$ref': '#/components/schemas/user'
examples:
response:
value:
id: 1234
email: test@example.com
name: Test user name
patch:
tags:
- Multiple examples
summary: Within `examples` (mixed)
description: "This operation has parameter and body examples alongside separately
maintained example within `examples` at the Media Type Object level.\n\n\U0001F4DA
OpenAPI specification references:\n\n* [3.0.3 Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject)\n\n*
[3.1.0 Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)"
parameters:
- name: param1
in: path
required: true
schema:
type: string
examples:
userRegistration:
summary: example summary (param 1)
description: a lengthier example description (param 1)
value: param1-example
yetAnotherParamExample:
value: param1-example-again
- name: param2
in: path
required: true
schema:
type: string
examples:
userRegistration:
summary: example summary (param 2)
description: a lengthier example description (param 2)
value: param2-example
- name: param3
in: query
schema:
type: string
examples:
userRegistration:
summary: example summary (param 3)
description: a lengthier example description (param 3)
value: param3-example
- name: param4
in: query
schema:
type: string
example: param4-example
- name: param5
in: header
required: true
schema:
type: string
examples:
userRegistration:
summary: example summary (param 5)
description: a lengthier example description (param 5)
value: param5-example
- name: param6
in: header
schema:
type: string
example: param6-example
requestBody:
required: true
content:
application/json:
schema:
'$ref': '#/components/schemas/user'
examples:
userRegistration:
value:
id: 1234
email: test@example.com
name: Test user name
userRegistration alt:
value:
id: 5678
email: test@example.com
name: Test user name
responses:
'200':
description: OK
content:
application/json:
schema:
'$ref': '#/components/schemas/user'
examples:
userRegistration:
value:
summary: example summary (response)
description: a lengthier example description (response)
id: 1234
email: test+response@example.com
name: Test user name (response)
response:
value:
id: 1234
email: test@example.com
name: Test user name
'400':
description: Validation failed
content:
application/xml:
examples:
response:
value: Invalid
user!
default:
description: OK
content:
application/json:
schema:
'$ref': '#/components/schemas/user'
examples:
response:
value:
id: 1234
email: test@example.com
name: Test user name
put:
tags:
- Single example
summary: Within `example`
description: "This operation has a param example and `requestBody` with separately
maintained example within a simple `example` object at the Media Type Object
level.\n\n\U0001F4DA OpenAPI specification references:\n\n* [3.0.3 Media Type
Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject)\n\n*
[3.1.0 Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)"
parameters:
- name: param1
in: path
required: true
schema:
type: string
example: param1-example
- name: param2
in: path
required: true
schema:
type: string
example: param2-example
requestBody:
required: true
content:
application/json:
schema:
'$ref': '#/components/schemas/user'
example:
id: 12343354
email: test@example.com
name: Test user name
responses:
'200':
description: OK
content:
application/json:
schema:
'$ref': '#/components/schemas/user'
example:
id: 12343354
email: test@example.com
name: Test user name
'/requestBody':
post:
tags:
- Multiple examples
summary: Within `examples` (body)
description: "This operation has a `requestBody` with separately maintained
examples within `examples` at the Media Type Object level.\n\n\U0001F4DA OpenAPI
specification references:\n\n* [3.0.3 Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject)\n\n*
[3.1.0 Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)"
requestBody:
required: true
content:
application/json:
schema:
'$ref': '#/components/schemas/user'
examples:
userRegistration:
value:
id: 1234
email: test@example.com
name: Test user name
userRegistration alt:
value:
id: 5678
email: test@example.com
name: Test user name
responses:
'200':
description: OK
content:
application/json:
schema:
'$ref': '#/components/schemas/user'
examples:
userRegistration:
summary: example summary (response)
description: a lengthier example description (response)
value:
id: 1234
email: test+response@example.com
name: Test user name (response)
response:
value:
id: 1234
email: test@example.com
name: Test user name
'400':
description: Validation failed
content:
application/xml:
examples:
response:
value: Invalid
user!
default:
description: OK
content:
application/json:
schema:
'$ref': '#/components/schemas/user'
examples:
response:
value:
id: 1234
email: test@example.com
name: Test user name
patch:
tags:
- Single example
summary: Within `example`
description: "This operation has a `requestBody` with separately maintained
example within a simple `example` object at the Media Type Object level.\n\n\U0001F4DA
OpenAPI specification references:\n\n* [3.0.3 Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject)\n\n*
[3.1.0 Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)"
requestBody:
required: true
content:
application/json:
schema:
'$ref': '#/components/schemas/user'
example:
id: 12343354
email: test@example.com
name: Test user name
responses:
'200':
description: OK
content:
application/json:
schema:
'$ref': '#/components/schemas/user'
example:
id: 12343354
email: test@example.com
name: Test user name
put:
tags:
- Single example
summary: '`$ref` within `example`'
description: "This operation has a `requestBody` with separately maintained
example within a `$ref` in a simple `example` object at the Media Type Object
level.\n\n\U0001F4DA OpenAPI specification references:\n\n* [3.0.3 Media Type
Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject)\n\n*
[3.1.0 Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)"
requestBody:
required: true
content:
application/json:
schema:
'$ref': '#/components/schemas/user'
example:
'$ref': '#/components/examples/user/value'
responses:
'200':
description: OK
content:
application/json:
schema:
'$ref': '#/components/schemas/user'
example:
'$ref': '#/components/examples/user/value'
'/requestBody-primitive-example':
post:
tags:
- Single example
summary: Primitive `example`
description: "This operation has a `requestBody` with separately maintained
**primitive** example within a simple `example` object at the Media Type Object
level.\n\n\U0001F4DA OpenAPI specification references:\n\n* [3.0.3 Media Type
Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject)\n\n*
[3.1.0 Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)"
requestBody:
required: true
content:
application/json:
schema:
type: string
example: column1,column2,column3,column4
responses:
'200':
description: OK
content:
application/json:
schema:
type: string
example: column1,column2,column3,column4
patch:
tags:
- Multiple examples
summary: Stringified JSON object in an `examples` value
description: "This operation has a `requestBody` with separately maintained
example within `examples` at the Media Type Object level containing stringified
JSON object.\n\n\U0001F4DA OpenAPI specification references:\n\n* [3.0.3 Media
Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject)\n\n*
[3.1.0 Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)"
requestBody:
required: true
content:
application/json:
schema:
'$ref': '#/components/schemas/pet'
examples:
cat:
summary: An example of a cat
value: |-
{
"name": "Fluffy",
"petType": "Cat"
}
dog:
summary: An example of a dog
value: |-
{
"name": "Buster",
"petType": "Dog"
}
responses:
'200':
description: OK
content:
application/json:
schema:
'$ref': '#/components/schemas/pet'
examples:
cat:
summary: An example of a cat
value: |-
{
"name": "Fluffy",
"petType": "Cat"
}
dog:
summary: An example of a dog
value: |-
{
"name": "Buster",
"petType": "Dog"
}
put:
tags:
- Multiple examples
summary: Stringified JSON arrays in an `examples` value
description: "This operation has a `requestBody` with separately maintained
example within `examples` at the Media Type Object level containing a stringified
JSON array.\n\n\U0001F4DA OpenAPI specification references:\n\n* [3.0.3 Media
Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject)\n\n*
[3.1.0 Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)"
requestBody:
required: true
content:
application/json:
schema:
'$ref': '#/components/schemas/pets'
examples:
cat:
summary: An example of a cat
value: |-
[
{
"name": "Fluffy",
"petType": "Cat"
}
]
dog:
summary: An example of a dog
value: |-
[
{
"name": "Buster",
"petType": "Dog"
}
]
responses:
'200':
description: OK
content:
application/json:
schema:
'$ref': '#/components/schemas/pets'
examples:
cat:
summary: An example of a cat
value: |-
[
{
"name": "Fluffy",
"petType": "Cat"
}
]
dog:
summary: An example of a dog
value: |-
[
{
"name": "Buster",
"petType": "Dog"
}
]
'/requestBody-multi-media-types':
post:
tags:
- Multiple media types
summary: Within `examples`
description: "This operation has a `requestBody` containing multiple media types
with each containing a separately maintained example within `examples` at
the Media Type Object level.\n\n\U0001F4DA OpenAPI specification references:\n\n*
[3.0.3 Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject)\n\n*
[3.1.0 Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)"
requestBody:
required: true
content:
text/plain:
examples:
response:
value: OK
application/json:
examples:
cat:
summary: An example of a cat
value:
name: Fluffy
petType: Cat
dog:
summary: An example of a dog
value:
name: Buster
petType: Dog
responses:
'200':
description: OK
content:
text/plain:
examples:
response:
value: OK
application/json:
examples:
cat:
summary: An example of a cat
value:
name: Fluffy
petType: Cat
dog:
summary: An example of a dog
value:
name: Buster
petType: Dog
'400':
description: Validation failed
content:
application/xml:
examples:
response:
value: Invalid
pet!
'/requestBody-form-data-example':
post:
summary: Demo handling of formData
operationId: demoFormData
requestBody:
content:
application/x-www-form-urlencoded:
schema:
required:
- client_id
- client_secret
type: object
properties:
client_id:
type: string
client_secret:
type: string
scope:
type: integer
format: int32
examples:
auth_example:
value:
client_id: id123
client_secret: secret456
scope: 789
required: false
responses:
'200':
description: Valid Token
content:
application/json:
schema:
'$ref': '#/components/schemas/Token'
examples:
auth_example:
value:
access_token: 123
token_type: type456
expires_in: 789
'401':
description: Unauthorized
components:
examples:
user:
value:
id: 12343354
email: test@example.com
name: Test user name
schemas:
pet:
type: object
properties:
name:
type: string
petType:
type: string
enum:
- Cat
- Dog
pets:
type: array
items:
'$ref': '#/components/schemas/pet'
tag:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
Token:
title: Token
required:
- access_token
- token_type
- expires_in
type: object
properties:
access_token:
type: integer
format: int32
token_type:
type: string
expires_in:
type: integer
format: int32
user:
type: object
properties:
id:
type: number
email:
type: string
name:
type: string