API settings

Configure OpenAPI and AsyncAPI specs, the interactive playground, code examples, and authentication in docs.json.

Use the api field in docs.json to configure what API specifications are available to generate API pages from; the interactive API playground users can test API endpoints with; and how to generate and display code examples.

Settings

api

Type: object

Define all API-related settings under the api key.

api.openapi · string or array or object

OpenAPI specification files for generating API reference pages. Accepts a single path or URL, an array of paths and URLs, or an object specifying a source and directory.

Show api.openapi object

source · string

URL or path to your OpenAPI specification file. Minimum length: 1.

directory · string

Directory to search for OpenAPI files. Do not include a leading slash.

Single file

"openapi": "openapi.json"

api.asyncapi · string or array or object

AsyncAPI specification files for generating event-driven API reference pages. Accepts a single path or URL, an array of paths and URLs, or an object specifying a source and directory.

Show api.asyncapi object

source · string

URL or path to your AsyncAPI specification file. Minimum length: 1.

directory · string

Directory to search for AsyncAPI files. Do not include a leading slash.

Single file

"asyncapi": "asyncapi.json"

api.playground · object

Interactive API playground settings.

Show api.playground

display · "interactive" | "simple" | "none" | "auth"

The display mode for the playground. Defaults to interactive.

• interactive — Full interactive playground with request builder
• simple — Simplified view without the request builder
• none — Hide the playground entirely
• auth — Show the playground only to authenticated users

proxy · boolean

Whether to route API requests through a proxy server. Defaults to true.

api.params · object

Display settings for API parameters.

Show api.params

expanded · "all" | "closed"

Whether to expand all parameters by default. Defaults to closed.

api.url · "full"

Display mode for the base URL in the endpoint header. Set to full to always show the complete base URL on every endpoint page. By default, the base URL is only shown when there are multiple base URLs to select from.

api.examples · object

Settings for autogenerated API code examples.

Show api.examples

languages · array of string

Languages for autogenerated code snippets. See supported languages for the full list of available languages and aliases.

defaults · "required" | "all"

Whether to include optional parameters in generated examples. Defaults to all.

prefill · boolean

Whether to prefill the playground with example values from your OpenAPI specification. Defaults to false.

autogenerate · boolean

Whether to generate code samples for endpoints from your API specification. Defaults to true. When set to false, only manually written code samples (from x-codeSamples in OpenAPI or <RequestExample> components in MDX) appear in the playground.

api.spec · object

OpenAPI specification display settings. Including the download button on API reference pages.

Show api.spec

download · boolean

Whether to show a download button for the OpenAPI spec on API reference pages. Defaults to false.

api.mdx · object

Settings for API pages built from MDX files rather than OpenAPI specs.

Show api.mdx

auth · object

Authentication configuration for MDX-based API requests.

Show auth

method · "bearer" | "basic" | "key" | "cobo"

Authentication method for API requests.

name · string

Authentication parameter name for API requests.

server · string or array

Base URL prepended to relative paths in page-level api frontmatter fields. Not used when the frontmatter contains a full URL.

Example

docs.json

{
  "api": {
    "openapi": ["openapi/v1.json", "openapi/v2.json"],
    "playground": {
      "display": "interactive"
    },
    "params": {
      "expanded": "all"
    },
    "url": "full",
    "examples": {
      "languages": ["curl", "python", "javascript", "go"],
      "defaults": "required",
      "prefill": true,
      "autogenerate": true
    },
    "spec": {
      "download": true
    }
  }
}