{
"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š 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š 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š 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š 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š 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š 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š 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š 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": "{\n \"name\": \"Fluffy\",\n \"petType\": \"Cat\"\n}"
},
"dog": {
"summary": "An example of a dog",
"value": "{\n \"name\": \"Buster\",\n \"petType\": \"Dog\"\n}"
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/pet"
},
"examples": {
"cat": {
"summary": "An example of a cat",
"value": "{\n \"name\": \"Fluffy\",\n \"petType\": \"Cat\"\n}"
},
"dog": {
"summary": "An example of a dog",
"value": "{\n \"name\": \"Buster\",\n \"petType\": \"Dog\"\n}"
}
}
}
}
}
}
},
"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š 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": "[\n {\n \"name\": \"Fluffy\",\n \"petType\": \"Cat\"\n }\n]"
},
"dog": {
"summary": "An example of a dog",
"value": "[\n {\n \"name\": \"Buster\",\n \"petType\": \"Dog\"\n }\n]"
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/pets"
},
"examples": {
"cat": {
"summary": "An example of a cat",
"value": "[\n {\n \"name\": \"Fluffy\",\n \"petType\": \"Cat\"\n }\n]"
},
"dog": {
"summary": "An example of a dog",
"value": "[\n {\n \"name\": \"Buster\",\n \"petType\": \"Dog\"\n }\n]"
}
}
}
}
}
}
}
},
"/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š 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"
}
}
}
}
}
}