@readme/oas-examples

{ "openapi": "3.0.3", "info": { "title": "ReadMe custom OpenAPI extensions demo", "description": "https://docs.readme.com/docs/openapi-extensions", "version": "1.0.0" }, "servers": [ { "url": "https://httpbin.org/anything" } ], "tags": [ { "name": "Custom code samples", "description": "https://docs.readme.com/docs/openapi-extensions#custom-code-samples" }, { "name": "Statically defined headers", "description": "https://docs.readme.com/docs/openapi-extensions#static-headers" }, { "name": "Toggling interactivity", "description": "https://docs.readme.com/docs/openapi-extensions#disable-the-api-explorer" }, { "name": "Designate code sample languages", "description": "https://docs.readme.com/docs/openapi-extensions#code-sample-languages" }, { "name": "Toggling our CORS proxy", "description": "https://docs.readme.com/docs/openapi-extensions#cors-proxy-enabled" }, { "name": "Toggling API Metrics", "description": "https://docs.readme.com/docs/openapi-extensions#disable-api-metrics" } ], "paths": { "/x-code-samples": { "post": { "operationId": "x-readme_code-samples", "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", "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 #3\".\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", "python", "node"] } }, "get": { "operationId": "x-code-samples", "summary": "Custom code samples with the \"x-code-samples\" extension", "description": "This is a demonstration of our handling of our `x-code-samples` extension.\n\n> If this is present alongside `x-readme.code-samples` then the `x-readme.code-samples` extension will take precedence over this extension.\n\nhttps://docs.readme.com/docs/openapi-extensions#custom-code-samples", "tags": ["Custom code samples"], "responses": { "200": { "description": "OK" } }, "x-code-samples": [ { "name": "Custom cURL snippet", "language": "curl", "code": "curl -X POST https://api.example.com/v2/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" } ] } }, "/x-headers": { "post": { "operationId": "x-readme_headers", "summary": "Static headers with the \"x-readme.headers\" extension", "description": "This is a demonstration of our handling of our `x-readme.headers` extension where when present, headers specified within it will be statically sent with API requests made in \"Try It\" and added into generated code snippets.\n\nIn this case we have statically defined an `x-api-key` header with the value of `static-value`.\n\nhttps://docs.readme.com/docs/openapi-extensions#static-headers", "tags": ["Statically defined headers"], "responses": { "200": { "description": "OK" } }, "x-readme": { "headers": [ { "key": "x-api-key", "value": "static-value" } ] } }, "patch": { "operationId": "x-headers", "summary": "Static headers with the \"x-headers\" extension", "description": "This is a demonstration of our handling of our `x-readme.headers` extension where when present, headers specified within it will be statically sent with API requests made in \"Try It\" and added into generated code snippets.\n\nIn this case we have statically defined an `x-api-key` header with the value of `static-value`.\n\n> If this is present alongside `x-readme.headers` then the `x-readme.headers` extension will take precedence over this extension.\n\nhttps://docs.readme.com/docs/openapi-extensions#static-headers", "tags": ["Statically defined headers"], "responses": { "200": { "description": "OK" } }, "x-headers": [ { "key": "x-api-key", "value": "static-value" } ] } }, "/x-explorer-enabled": { "post": { "operationId": "x-readme_explorer-enabled", "summary": "Disable interactivity with the \"x-readme.explorer-enabled\" extension", "description": "When `x-readme.explorer-enabled` is present on an operation and set to `false`, the reference guide will be non-interactive and though your users will still be able to fill out a form and receive an auto-generated code sample to use, they will not be able to make requests to your API with our \"Try It\" button.\n\nhttps://docs.readme.com/docs/openapi-extensions#disable-the-api-explorer", "tags": ["Toggling interactivity"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } }, "required": true }, "responses": { "200": { "description": "OK" } }, "security": [ { "petstore_auth": ["write:pets", "read:pets"] } ], "x-readme": { "explorer-enabled": false } }, "patch": { "operationId": "x-explorer-enabled", "summary": "Disable interactivity with the \"x-explorer-enabled\" extension", "description": "When `x-explorer-enabled` is present on an operation and set to `false`, the reference guide will be non-interactive and though your users will still be able to fill out a form and receive an auto-generated code sample to use, they will not be able to make requests to your API with our \"Try It\" button.\n\nIn this case we have statically defined an `x-api-key` header with the value of `static-value`.\n\n> If this is present alongside `x-readme.explorer-enabled` then the `x-readme.explorer-enabled` extension will take precedence over this extension.\n\nhttps://docs.readme.com/docs/openapi-extensions#disable-the-api-explorer", "tags": ["Toggling interactivity"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } }, "required": true }, "responses": { "200": { "description": "OK" } }, "security": [ { "petstore_auth": ["write:pets", "read:pets"] } ], "x-explorer-enabled": false } }, "/x-samples-languages": { "get": { "operationId": "x-readme_samples-languages", "summary": "Control available code sample languages the \"x-readme.samples-languages\" extension", "description": "With an array of languages present in `x-readme.samples-languages` code samples will be generated for only those languages. If not present, it will default to: `curl`, `node`, `ruby`, `javascript`, and `python`.\n\nhttps://docs.readme.com/guides/docs/openapi-extensions#code-sample-languages", "tags": ["Designate code sample languages"], "responses": { "200": { "description": "OK" } }, "x-readme": { "samples-languages": ["swift"] } }, "post": { "operationId": "x-samples-languages", "summary": "Control available code sample languages the \"x-samples-languages\" extension", "description": "With an array of languages present in `x-samples-languages` code samples will be generated for only those languages. If not present, it will default to: `curl`, `node`, `ruby`, `javascript`, and `python`.\n\n> If this is present alongside `x-readme.samples-languages` then the `x-readme.samples-languages` extension will take precedence over this extension.\n\nhttps://docs.readme.com/guides/docs/openapi-extensions#code-sample-languages", "tags": ["Designate code sample languages"], "responses": { "200": { "description": "OK" } }, "x-samples-languages": ["swift"] } }, "/x-proxy-enabled": { "post": { "operationId": "x-readme_proxy-enabled", "summary": "Disable funneling requests through our CORS proxy with the \"x-readme.proxy-enabled\" extension", "description": "When `x-readme.proxy-enabled` is set to `false` all requests from the interactive API Explorer will be funneled directly to the configured server URL, otherwise they will be piped through our proxy to allow [CORS-enabled](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) requests for you.\n\nhttps://docs.readme.com/docs/openapi-extensions#cors-proxy-enabled", "tags": ["Toggling our CORS proxy"], "responses": { "200": { "description": "OK" } }, "x-readme": { "proxy-enabled": false } }, "patch": { "operationId": "x-proxy-enabled", "summary": "Disable funneling requests through our CORS proxy with the \"x-proxy-enabled\" extension", "description": "When `x-proxy-enabled` is set to `false` all requests from the interactive API Explorer will be funneled directly to the configured server URL, otherwise they will be piped through our proxy to allow [CORS-enabled](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) requests for you.\n\n> If this is present alongside `x-readme.proxy-enabled` then the `x-readme.proxy-enabled` extension will take precedence over this extension.\n\nhttps://docs.readme.com/docs/openapi-extensions#cors-proxy-enabled", "tags": ["Toggling our CORS proxy"], "responses": { "200": { "description": "OK" } }, "x-proxy-enabled": false } }, "/x-metrics-enabled": { "post": { "operationId": "x-readme_metrics-enabled", "summary": "Disable tracking requests through our API Metrics product with the \"x-readme.metrics-enabled\" extension", "description": "When `x-readme.metrics-enabled` is set to `false` all requests from the interactive API Explorer will not be tracked for you within our [API Metrics product](https://readme.com/metrics) and you will not see any requests on that operations reference page that may have been logged to API Metrics through one of our many SDKs.\n\nhttps://docs.readme.com/docs/openapi-extensions#disable-api-metrics", "tags": ["Toggling API Metrics"], "responses": { "200": { "description": "OK" } }, "x-readme": { "metrics-enabled": false } }, "patch": { "operationId": "x-metrics-enabled", "summary": "Disable tracking requests through our API Metrics product with the \"x-metrics-enabled\" extension", "description": "When `x-metrics-enabled` is set to `false` all requests from the interactive API Explorer will not be tracked for you within our [API Metrics product](https://readme.com/metrics) and you will not see any requests on that operations reference page that may have been logged to API Metrics through one of our many SDKs.\n\nhttps://docs.readme.com/docs/openapi-extensions#disable-api-metrics", "tags": ["Toggling API Metrics"], "responses": { "200": { "description": "OK" } }, "x-metrics-enabled": false } } }, "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"] } } } } } }