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
x-readme.explorer-enabledtrue

Disable code examples

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

ExtensionDefault value
x-readme.samples-enabledtrue

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)
Cc
C++cplusplus
C#csharp
Clojureclojure
cURLcurl
Gogo
Javajava
JSjavascript
Kotlinkotlin
Node.jsnode
Node.js (simple)*node-simple
Objective-Cobjectivec
OCamlocaml
PHPphp
PowerShellpowershell
Pythonpython
Rr
Rubyruby
Swiftswift

* 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 on our redesign that we're slowly rolling to projects. Contact our support team to get early access.

Enables you to set custom code samples on your operations.

ExtensionDefault value
x-readme.code-samples[]

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 https://api.example.com/v2/alert"
    },
  ]
}

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
x-readme.proxy-enabledtrue

Static headers

An array of static headers to add to each request.

ExtensionDefault value
x-readme.headers[]

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

x-send-defaults is now deprecated, 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
x-readme.send-defaultsfalse

Authentication defaults

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": "https://example.com/oauth/authorize",
        "tokenUrl": "https://example.com/oauth/token",
        "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?