@readme/oas-examples

{ "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": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><note><body>Invalid user!</body></note>" } } } } }, "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": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><note><body>Invalid user!</body></note>" } } } } }, "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": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><note><body>Invalid user!</body></note>" } } } } }, "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": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><note><body>Invalid pet!</body></note>" } } } } } } } }, "/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" } } } } } }