Logo
Docs

API reference

Radiant can generate API reference pages from OpenAPI sources. Use this when you want endpoint documentation, request and response details, and playground behavior to stay aligned with your API specification.

OpenAPI reference pages also improve Ask AI answers about exact methods, paths, parameters, request bodies, responses, and errors.

OpenAPI sources

OpenAPI sources can be:

  • Local .json, .yaml, or .yml files inside the docs root.
  • Public http:// or https:// URLs that return OpenAPI JSON or YAML.

Local OpenAPI paths are relative to the docs root and should not start with /.

docs.jsonopenapi.jsonapi/  admin.openapi.yaml

Generate a full API reference

Use top-level OpenAPI navigation when the docs site is primarily an API reference:

{  "navigation": {    "openapi": "openapi.json"  }}

Use an object when you need filters:

{  "navigation": {    "openapi": {      "source": "openapi.json",      "include": ["GET /customers", "POST /customers"]    }  }}

include and exclude are mutually exclusive. Use endpoint strings in the METHOD /path format.

Add API reference to a menu

Use navigation.menu when you want guides and API reference sections side by side.

{  "navigation": {    "menu": {      "type": "segmented",      "items": [        {          "label": "Guides",          "pages": ["getting-started/quickstart"]        },        {          "label": "API Reference",          "openapi": {            "source": "openapi.json"          }        }      ]    }  }}

Each menu item must contain either pages or openapi.

Add API reference to tabs

Use navigation.tabs when API reference should be a primary section above the sidebar.

{  "navigation": {    "tabs": {      "presentation": "topbar",      "items": [        {          "label": "Guides",          "pages": ["getting-started/quickstart"]        },        {          "label": "API Reference",          "slug": "api",          "openapi": {            "source": "openapi.json"          }        }      ]    }  }}

Each tab must contain one of pages, menu, or openapi. If presentation is omitted, tabs use topbar.

Add one endpoint page

Use an OpenAPI page item when you want a specific endpoint to appear alongside other pages in a normal pages navigation structure.

{  "navigation": {    "pages": [      "getting-started/quickstart",      {        "openapi": {          "source": "openapi.json",          "endpoint": "GET /customers"        },        "title": "List customers"      }    ]  }}

Radiant validates that the endpoint exists in the source file.

Use endpoint links when MDX prose should point to generated OpenAPI endpoint pages. Link to the endpoint identity, not the generated browser URL.

Use the shorthand form when exactly one rendered OpenAPI source contains the endpoint:

[List customers](<GET /customers>)

Markdown link destinations with spaces must be wrapped in angle brackets. The angle brackets are not part of the rendered link.

If more than one rendered OpenAPI source contains the same method and path, add the OpenAPI source before the endpoint:

[List customers](<api/openapi.yaml#GET /customers>)

Use the same source string that appears in docs.json. If the source is a remote URL, use that URL before #GET /path.

Component href props use the same endpoint target as a quoted string:

<Card title="List customers" href="GET /customers">  Review request and response details.</Card>

Endpoint links are valid only when the endpoint is rendered as a page. This means validation checks both the OpenAPI source and the docs.json navigation that generates pages.

SituationResult
The endpoint is rendered by one OpenAPI sourceShorthand link works
The endpoint is rendered by multiple OpenAPI sourcesUse the explicit source form
The endpoint exists but is excluded or omitted from includeValidation fails
The endpoint exists only in an OpenAPI source that is not renderedValidation fails
The endpoint does not exist in the sourceValidation fails

Do not link directly to generated endpoint URLs such as /api-reference/customers-get. Radiant rewrites endpoint links to the correct generated URL during the build.

Published OpenAPI output

When Radiant builds API reference pages from a local OpenAPI source, the published docs site also exposes that spec at its public path, such as /openapi.json or /api/openapi.json.

Generated endpoint pages also have Markdown versions. Endpoint Markdown includes the method, path, parameters, request body, responses, a link to the full spec, and a compact OpenAPI operation block with the schemas and security schemes referenced by that endpoint.

API playground proxy

The API playground can send requests through Radiant’s hosted proxy. The proxy is enabled by default.

Disable it with playground.proxy:

{  "playground": {    "proxy": false  }}

When the proxy is enabled, Radiant builds an allowlist from HTTPS server origins in the OpenAPI servers list. Playground requests must target one of those origins.

Write better API reference content

Radiant uses your OpenAPI source to render endpoint pages and prepare assistant context. Fill in:

  • Operation summaries and descriptions.
  • Parameter descriptions.
  • Request body descriptions and schemas.
  • Response descriptions and examples.
  • Error responses.
  • Authentication details.

The more complete your OpenAPI source is, the more useful the generated API reference and Ask AI answers become.

Common questions

Yes. The URL must return OpenAPI JSON or YAML. If the URL returns HTML, validation fails.

Yes. Use include to list the endpoints to show, or exclude to hide endpoints from a larger generated reference. Do not use both in the same OpenAPI object.

Endpoint page items must use an endpoint that exists in the OpenAPI source, written as METHOD /path, for example GET /customers.

Yes. Generated API reference pages give Ask AI structured context for exact methods, paths, parameters, request bodies, responses, and errors.

Next pages

Navigation

Place API sections.
Write docs for better answers

Improve AI retrieval.
Use the CLI

Preview source changes.