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. 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 #3". 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 description: |- This is a demonstration of our handling of our `x-code-samples` extension. > If this is present alongside `x-readme.code-samples` then the `x-readme.code-samples` extension will take precedence over this extension. https://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". curl -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. In this case we have statically defined an `x-api-key` header with the value of `static-value`. https://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. In this case we have statically defined an `x-api-key` header with the value of `static-value`. > If this is present alongside `x-readme.headers` then the `x-readme.headers` extension will take precedence over this extension. https://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. https://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. In this case we have statically defined an `x-api-key` header with the value of `static-value`. > If this is present alongside `x-readme.explorer-enabled` then the `x-readme.explorer-enabled` extension will take precedence over this extension. https://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`. https://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`. > If this is present alongside `x-readme.samples-languages` then the `x-readme.samples-languages` extension will take precedence over this extension. https://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. https://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. > If this is present alongside `x-readme.proxy-enabled` then the `x-readme.proxy-enabled` extension will take precedence over this extension. https://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. https://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. https://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