OpenAPI Extensions

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 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:

{
  "openapi": "3.0.2",
  "info": {
    "title": "Owl Parliament",
    "description": "This is a sample Owl Parliament Server",
    "version": "1.0.0"
  },
  "x-readme": {
    "explorer-enabled": false,
    "proxy-enabled": false,
    "samples-languages": ["shell", "python", "go"]
  }
}

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

{
  "openapi": "3.0.2",
  "info": {
    "title": "Owl Parliament",
    "description": "This is a sample Owl Parliament Server",
    "version": "1.0.0"
  },
  "x-explorer-enabled": false,
  "x-proxy-enabled": false,
  "x-samples-languages": ["shell", "python", "go"]
}

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.

{
  "paths": {
    "/owl": {
      "post": {
        "summary": "Add a new owl to the parliament",
        "description": "Adds a new owl to the parliament",
        "operationId": "addOwl",
        "x-readme": {
          "samples-languages": ["shell", "python", "go"]
        }
      }
    }
  }
}

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

{
  "paths": {
    "/owl": {
      "post": {
        "summary": "Add a new owl to the parliament",
        "description": "Adds a new owl to the parliament",
        "operationId": "addOwl",
        "x-proxy-enabled": false,
        "x-samples-languages": ["shell", "python", "go"]
      }
    }
  }
}

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.