## Getting Started

[Extensions](🔗) are properties added to an OpenAPI spec that customize your API Reference user experience. All of these properties are optional.

ReadMe extensions are defined by the `x-readme` object and most can be placed either on the root level of your spec, or on the operation level. See the [Extension Usage](🔗) section below for specific details.

Want to see a spec file that utilizes these extensions? Take a look at the example demo spec file [here](🔗).

## Usage

Unless otherwise noted below all of our custom OpenAPI extensions can be defined on the root level of your API definition within a `x-readme` object:

If you don't want to use `x-readme` in your spec, you can define each extension as `x-<extension_name>` instead:

### Operation-level usage

You can also define each extension on the operation-level to individually control their functionality on an operation-by-operation basis. If an extension is defined at both the operation and root levels, the operation-level extension takes presedence.

You can also define the extension using the `x-<extension_name>` format instead:

## Available Extensions

### Disable the API Explorer

Disables the API Explorer's "Try It" button, preventing users from making API requests from within your docs. Users will still be able to fill out any entry fields (path or query parameters, etc.), and code snippets will be auto-generated based on the user's input, however to interact with your API the user will need to copy the code snippet and execute it outside of your docs.

This **does not** disable your API Reference documentation.

<!-- prettier-ignore-start -->

<!-- prettier-ignore-end -->

<!-- prettier-ignore-start -->

<!-- prettier-ignore-end -->

### Code sample languages

Toggles what languages are shown by default for code samples in the API Explorer. This only affects what languages are initially shown to the user; if the user picks another language from the three-dot menu, that language and the respective auto-generated code snippet will also appear as an option in the API Explorer.

❗



We built a Node package called [`api`](🔗) that magically generates an SDK from an OpenAPI definition! To see `api` in action visit our [API documentation](🔗)!

<!-- prettier-ignore-start -->

<!-- prettier-ignore-end -->

These are the languages supported by way of the [httpsnippet](🔗) library:

<!--This table was grabbed from here: https://github.com/readmeio/oas-to-snippet#supported-languages -->

<!-- prettier-ignore-start -->

<!-- prettier-ignore-end -->

\*This column documents any supported HTTP libraries for a given language mode. The `x-readme.samples-languages` array should contain language values (i.e. values from the second column like `node` or `php`) and **not** library names (i.e., values from the third column like `axios` or `guzzle`).

<!-- prettier-ignore-start -->

<!-- prettier-ignore-end -->

### Custom code samples

Enables custom-written code samples to be set for your operations. Use this if you have specific formatting that may not be followed by the auto-generated code samples.

❗



Custom code samples are treated as static content, so it's not possible to populate a code sample with [enduser data from a custom login (JWT)](🔗).

❗



This extension can only be set on the operation level

<!-- prettier-ignore-start -->

<!-- prettier-ignore-end -->

This must be provided as an array of JSON objects containing:

<!-- prettier-ignore-start -->

<!-- prettier-ignore-end -->

<!-- prettier-ignore-start -->

<!-- prettier-ignore-end -->

### CORS proxy enabled

Toggles the CORS proxy used when making API requests from within your docs (via the "Try It" button). If your API is already set up to return CORS headers, you can safely disable this feature.

Disabling the CORS proxy will make the request directly from the user's browser and will prevent [Metrics](🔗) data from being logged by us unless [Metrics have already set up on your backend](🔗).

<!-- prettier-ignore-start -->

<!-- prettier-ignore-end -->

### Static headers

Adds static headers to add to each request. Use this when there are specific headers unique to your API.

<!-- prettier-ignore-start -->

<!-- prettier-ignore-end -->

Headers must be provided as an array of objects with `key` and `value` properties.

<!-- prettier-ignore-start -->

<!-- prettier-ignore-end -->

### Authentication defaults

Sets the default API Key or OAuth2 token used when making API requests from your docs. Other authentication types are not supported.

Unlike the other extensions we provide, authentication defaults are set using `x-default` in your `securitySchemes` object. Defaults can only be set for `oauth2` and `apiKey` authentication types.

### Disable API Metrics

Disables API requests from the API Explorer's "Try It" button from being sent into our [API Metrics](🔗) for you and your users. Additionally on any API endpoint that this is disabled on your users will not see lists or graphs of previous requests they've made against that API endpoint — either through the API Explorer's interactivity or through one of our [Metrics SDKs](🔗) (if you have those installed on your API).

<!-- prettier-ignore-start -->

<!-- prettier-ignore-end -->

## Deprecated and Unsupported Extensions

The extensions below are deprecated or are no longer supported in the most recent version of the [API Reference Design](🔗). These are documented for reference purposes only.

### 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.

<!-- prettier-ignore-start -->

<!-- prettier-ignore-end -->

### 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.

<!-- prettier-ignore-start -->

<!-- prettier-ignore-end -->

## Support

Questions? [Contact Support](🔗), we don't bite!