From 32fdf8dd1070b8e95fdf5845d3a5cec081a4529d Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 17 Apr 2024 16:25:23 -0500 Subject: [PATCH 1/4] feat: support for param examples --- 3.0/json/request-examples.json | 302 ++++++++++++++++++++++++++++++++- 1 file changed, 299 insertions(+), 3 deletions(-) diff --git a/3.0/json/request-examples.json b/3.0/json/request-examples.json index e38b860..827dac8 100644 --- a/3.0/json/request-examples.json +++ b/3.0/json/request-examples.json @@ -1,7 +1,7 @@ { "openapi": "3.0.0", "info": { - "title": "Support for request body examples", + "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" }, @@ -22,11 +22,298 @@ } ], "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" + } + } + } + ], + "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`", - "description": "This operation has a `requestBody` with 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)", + "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": { @@ -62,6 +349,15 @@ "$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, From 2df7dc97efb9adddde4994ef4c662e4d9764f271 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 17 Apr 2024 16:25:51 -0500 Subject: [PATCH 2/4] feat: add corresponding example to x-readme.code-samples --- 3.0/json/readme-extensions.json | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/3.0/json/readme-extensions.json b/3.0/json/readme-extensions.json index 5514f0a..40133bd 100644 --- a/3.0/json/readme-extensions.json +++ b/3.0/json/readme-extensions.json @@ -45,7 +45,23 @@ "tags": ["Custom code samples"], "responses": { "200": { - "description": "OK" + "description": "OK", + "content": { + "application/json": { + "examples": { + "TestExample": { + "summary": "An example of a cat", + "value": { + "name": "Fluffy", + "petType": "Cat", + "color": "White", + "gender": "male", + "breed": "Persian" + } + } + } + } + } } }, "x-readme": { @@ -54,13 +70,21 @@ "name": "Custom cURL snippet", "language": "curl", "code": "curl -X POST https://api.example.com/v2/alert", + "install": "brew install curl", + "correspondingExample": "TestExample" + }, + { + "name": "Another cURL snippet", + "language": "curl", + "code": "curl -X POST https://api.example.com/v2/another-alert", "install": "brew install curl" }, { "language": "curl", "code": "# This custom cURL snippet does not have a custom name so it has the name of \"Default #2\".\n\ncurl -X POST https://api.example.com/v2/alert" } - ] + ], + "samples-languages": ["shell"] } }, "get": { From 9c0441a762a078a6f2a505270daeda475a31e958 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 17 Apr 2024 16:28:59 -0500 Subject: [PATCH 3/4] feat: fluff out code-samples even more --- 3.0/json/readme-extensions.json | 69 +++++++++++++++++++++++++++++++-- 1 file changed, 66 insertions(+), 3 deletions(-) diff --git a/3.0/json/readme-extensions.json b/3.0/json/readme-extensions.json index 40133bd..fbe0d8e 100644 --- a/3.0/json/readme-extensions.json +++ b/3.0/json/readme-extensions.json @@ -43,6 +43,32 @@ "summary": "Custom code samples with the \"x-readme.code-samples\" extension", "description": "This is a demonstration of our handling of our `x-readme.code-samples` extension.\n\nhttps://docs.readme.com/docs/openapi-extensions#custom-code-samples", "tags": ["Custom code samples"], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Tag" + }, + "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", @@ -62,6 +88,21 @@ } } } + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "examples": { + "curlExample": { + "summary": "An example of a cat", + "value": { + "missing": "can't find your stuff dawg" + } + } + } + } + } } }, "x-readme": { @@ -76,15 +117,37 @@ { "name": "Another cURL snippet", "language": "curl", - "code": "curl -X POST https://api.example.com/v2/another-alert", - "install": "brew install curl" + "code": "http POST https://api.example.com/v2/another-alert", + "install": "brew install httpie", + "correspondingExample": "curlExample" }, { "language": "curl", "code": "# This custom cURL snippet does not have a custom name so it has the name of \"Default #2\".\n\ncurl -X POST https://api.example.com/v2/alert" + }, + { + "name": "Yet another custom snippet", + "language": "curl", + "code": "curl -X POST https://api.example.com/v2/alert", + "install": "brew install curl", + "correspondingExample": "TestExample" + }, + { + "name": "Yet another custom snippet", + "language": "python", + "code": "import requests\n\nprint(\"do something idk\")", + "install": "pip install requests", + "correspondingExample": "TestExample" + }, + { + "name": "Yet another custom snippet", + "language": "node", + "code": "import something from 'requestidk';\n\nconsole.log('do something idk');", + "install": "npm install requestidk", + "correspondingExample": "curlExample" } ], - "samples-languages": ["shell"] + "samples-languages": ["shell", "python", "node"] } }, "get": { From d3acb99e9b9f08526c93cb8fc90217509115d940 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 17 Apr 2024 16:57:38 -0500 Subject: [PATCH 4/4] feat: also port changes over to yaml --- 3.0/yaml/readme-extensions.yaml | 68 ++++++++++ 3.0/yaml/request-examples.yaml | 216 +++++++++++++++++++++++++++++++- 2 files changed, 281 insertions(+), 3 deletions(-) diff --git a/3.0/yaml/readme-extensions.yaml b/3.0/yaml/readme-extensions.yaml index fe37039..b57b0bc 100644 --- a/3.0/yaml/readme-extensions.yaml +++ b/3.0/yaml/readme-extensions.yaml @@ -29,20 +29,88 @@ paths: https://docs.readme.com/docs/openapi-extensions#custom-code-samples tags: - Custom code samples + requestBody: + required: true + content: + application/json: + schema: + '$ref': '#/components/schemas/Tag' + 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: + examples: + TestExample: + summary: An example of a cat + value: + name: Fluffy + petType: Cat + color: White + gender: male + breed: Persian + '404': + description: Not Found + content: + application/json: + examples: + curlExample: + summary: An example of a cat + value: + missing: can't find your stuff dawg x-readme: code-samples: - name: Custom cURL snippet language: curl code: curl -X POST https://api.example.com/v2/alert install: brew install curl + correspondingExample: TestExample + - name: Another cURL snippet + language: curl + code: http POST https://api.example.com/v2/another-alert + install: brew install httpie + correspondingExample: curlExample - language: curl code: |- # This custom cURL snippet does not have a custom name so it has the name of "Default #2". curl -X POST https://api.example.com/v2/alert + - name: Yet another custom snippet + language: curl + code: curl -X POST https://api.example.com/v2/alert + install: brew install curl + correspondingExample: TestExample + - name: Yet another custom snippet + language: python + code: |- + import requests + + print("do something idk") + install: pip install requests + correspondingExample: TestExample + - name: Yet another custom snippet + language: node + code: |- + import something from 'requestidk'; + + console.log('do something idk'); + install: npm install requestidk + correspondingExample: curlExample + samples-languages: + - shell + - python + - node get: operationId: x-code-samples summary: Custom code samples with the "x-code-samples" extension diff --git a/3.0/yaml/request-examples.yaml b/3.0/yaml/request-examples.yaml index 7ac727a..ee98ba8 100644 --- a/3.0/yaml/request-examples.yaml +++ b/3.0/yaml/request-examples.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - title: Support for request body examples + 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: @@ -10,13 +10,216 @@ tags: - 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 + 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` + summary: Within `examples` (body) description: "This operation has a `requestBody` with separately maintained - example within `examples` at the Media Type Object level.\n\n\U0001F4DA OpenAPI + 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: @@ -44,6 +247,13 @@ paths: 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