ReadMe Documentation

ReadMe Documentation

Welcome to the ReadMe Documentation, where you'll find comprehensive guides and community support to help you start working with ReadMe as quickly as possible!

Get Started

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
cURLcurl
Gogo
Javajava
JSjavascript
Kotlinkotlin
Node.jsnode
Node.js (simple)*node-simple
Objective-Cobjectivec
PHPphp
PowerShellpowershell
Pythonpython
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!

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-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, we'd like to add abcdefg12345 as a default token on our 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 auth tooltip in your explorer, abcdefg12345 will be set as the default token.


Did this page help you?