diff --git a/3.0/json/example-groups.json b/3.0/json/example-groups.json new file mode 100644 index 0000000..f3a9539 --- /dev/null +++ b/3.0/json/example-groups.json @@ -0,0 +1,151 @@ +{ + "openapi": "3.0.3", + "info": { + "title": "Example Groups Demo", + "description": "https://docs.readme.com/docs/openapi-extensions", + "version": "1.0.0" + }, + "servers": [{ "url": "https://httpbin.org/anything" }], + "tags": [ + { + "name": "Example Groups", + "description": "https://docs.readme.com/main/docs/openapi-extensions#corresponding-response-examples" + } + ], + "paths": { + "/x-code-samples": { + "post": { + "operationId": "x-readme_code-samples_example-groups", + "summary": "Custom Code Sample with `correspondingExample` ", + "description": "This is a demonstration of our example group pairing with our `x-readme.code-samples` extension via the `correspondingExample` key.\n\nhttps://docs.readme.com/main/docs/openapi-extensions#corresponding-response-examples", + "tags": ["Example Groups"], + "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": { + "TestExample1": { + "summary": "An example of a cat", + "value": { + "name": "Fluffy", + "petType": "Cat", + "color": "White", + "gender": "male", + "breed": "Persian" + } + }, + "curlExample": { + "summary": "An example of a dog", + "value": { + "name": "Fluffy", + "petType": "Dog", + "color": "White", + "gender": "male", + "breed": "Husky" + } + } + } + } + } + } + }, + "x-readme": { + "code-samples": [ + { + "correspondingExample": "TestExample1", + "name": "Custom cURL snippet", + "language": "curl", + "code": "curl -X POST https://api.example.com/v2/alert", + "install": "brew install curl" + }, + { + "name": "Another cURL snippet", + "language": "curl", + "code": "curl -X POST https://api.example.com/v2/another-alert", + "install": "brew install curl", + "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" + } + ], + "samples-languages": ["shell"] + } + } + } + }, + "components": { + "securitySchemes": { + "petstore_auth": { + "type": "oauth2", + "flows": { + "implicit": { + "authorizationUrl": "http://petstore.swagger.io/oauth/dialog", + "scopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } + } + } + } + }, + "schemas": { + "Tag": { + "type": "object", + "properties": { + "id": { "type": "integer", "format": "int64" }, + "name": { "type": "string" } + } + }, + "Pet": { + "type": "object", + "required": ["name", "photoUrls"], + "properties": { + "id": { "type": "integer", "format": "int64" }, + "name": { "type": "string", "example": "doggie" }, + "photoUrls": { "type": "array", "items": { "type": "string" } }, + "tags": { + "type": "array", + "items": { "$ref": "#/components/schemas/Tag" } + }, + "status": { + "type": "string", + "description": "pet status in the store", + "enum": ["available", "pending", "sold"] + } + } + } + } + }, + "x-readme": { + "explorer-enabled": true, + "proxy-enabled": true, + "samples-enabled": true + } +} diff --git a/3.0/yaml/example-groups.yaml b/3.0/yaml/example-groups.yaml new file mode 100644 index 0000000..9a3fbab --- /dev/null +++ b/3.0/yaml/example-groups.yaml @@ -0,0 +1,134 @@ +openapi: 3.0.3 +info: + title: Example Groups Demo + description: 'https://docs.readme.com/docs/openapi-extensions' + version: 1.0.0 +servers: + - url: 'https://httpbin.org/anything' +tags: + - name: Example Groups + description: >- + https://docs.readme.com/main/docs/openapi-extensions#corresponding-response-examples +paths: + /x-code-samples: + post: + operationId: x-readme_code-samples_example-groups + summary: 'Custom Code Sample with `correspondingExample` ' + description: >- + This is a demonstration of our example group pairing with our + `x-readme.code-samples` extension via the `correspondingExample` key. + + + https://docs.readme.com/main/docs/openapi-extensions#corresponding-response-examples + tags: + - Example Groups + 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: + TestExample1: + summary: An example of a cat + value: + name: Fluffy + petType: Cat + color: White + gender: male + breed: Persian + curlExample: + summary: An example of a dog + value: + name: Fluffy + petType: Dog + color: White + gender: male + breed: Husky + x-readme: + code-samples: + - correspondingExample: TestExample1 + name: Custom cURL snippet + language: curl + code: 'curl -X POST https://api.example.com/v2/alert' + install: brew install curl + - name: Another cURL snippet + language: curl + code: 'curl -X POST https://api.example.com/v2/another-alert' + install: brew install curl + 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 + samples-languages: + - shell +components: + securitySchemes: + petstore_auth: + type: oauth2 + flows: + implicit: + authorizationUrl: 'http://petstore.swagger.io/oauth/dialog' + scopes: + 'write:pets': modify pets in your account + 'read:pets': read your pets + schemas: + Tag: + type: object + properties: + id: + type: integer + format: int64 + name: + type: string + Pet: + type: object + required: + - name + - photoUrls + properties: + id: + type: integer + format: int64 + name: + type: string + example: doggie + photoUrls: + type: array + items: + type: string + tags: + type: array + items: + $ref: '#/components/schemas/Tag' + status: + type: string + description: pet status in the store + enum: + - available + - pending + - sold +x-readme: + explorer-enabled: true + proxy-enabled: true + samples-enabled: true