OpenAPI Extensions

We've added a few OpenAPI extensions to help you better integrate with ReadMe.

All of these properties are optional, and with the exception of authentication defaults, and should be set at the top level of your OpenAPI document. We also support operation level extensions to provide greater control over which endpoints have which extensions. View the examples here and the associated Swagger file here!


If you wish to not nest our custom OpenAPI extensions under an x-readme group, you can (with the exception of x-default), define them by themselves as x-<extension_name> instead.

Disable the API Explorer

Completely disable our API Explorer and prevent your users from interacting with the API by filling out the form and making API requests. Note that this will not disable your API Reference documentation, just their ability to interact with your API.

ExtensionDefault value

Disable code examples


This extension is no longer supported in the new API Reference Design.

Disable auto-generated code samples from appearing on your API Reference operation documentation.

ExtensionDefault value

Code sample languages

Toggle what languages we will generate code samples for.

ExtensionDefault value
x-readme.samples-languages['curl', 'node', 'ruby', 'javascript', 'python']

We support a number of different languages by way of the httpsnippet library:

LanguageAvailable language mode(s)
Node.js (simple)*node-simple

* We built an SDK called api which makes it easier than ever to generate an SDK using just an OpenAPI file πŸš€ see api in action in the ReadMe API documentation!

Custom code samples


This extension is only available with the new API Reference Design.

Enables you to set custom code samples on your operations.

ExtensionDefault value

This must be provided as an array of JSON objects that contain the following:

  • language: The language that the code sample is written in. See above for a list of supported languages.
  • code: This is your custom code!
  • name: A helpful descriptor for what this code sample is. This optional, though, so if you don't supply this we'll name it as "Default" for your users.
"x-readme": {
  "code-samples": [
      "language": "php",
      "code": "<?php echo \"This is our custom PHP code\"; ?>"
      "language": "curl",
      "code": "curl -X POST"

CORS proxy enabled

Toggles whether our CORS proxy is enabled or not when making API requests through your reference guide. If your API is already set up to return CORS headers, you can safely turn this off.

ExtensionDefault value

Static headers

An array of static headers to add to each request.

ExtensionDefault value

Must be provided as an array of JSON objects with key and value properties. For example:

"x-readme": {
  "headers": [
    { "key": "X-Static-Header", "value": "owlbert" }

Send defaults


This extension is deprecated and all defaults will be sent via the API Explorer.

Whether to send the defaults specified in your OpenAPI document, or render them as placeholders.

ExtensionDefault value

Authentication defaults


This extension only supports API Key / OAuth2 tokens.

If you wish to set up default authentication data in your explorer, you can do so by adding an x-default extension in your security component. For example, if you'd like to add abcdefg12345 as a default token on your oauth security scheme that's being used on some operations:

"securitySchemes": {
  "oauth": {
    "type": "oauth2",
    "x-default": "abcdefg12345",
    "flows": {
      "authorizationCode": {
        "authorizationUrl": "",
        "tokenUrl": "",
        "scopes": {}

When users click into your authentication tooltip in your API Reference, abcdefg12345 will be set as the default token.

Did this page help you?