OpenAPI integration

Generate API reference documentation from OpenAPI specifications.

You can generate a complete API reference from an OpenAPI specification. Drop your spec file into your content directory, configure it in docs.json, and blode.md creates a page for every operation.

Setup

Add your spec file

Place an openapi.yaml or openapi.json file in your content directory:

docs.json

index.mdx

openapi.yaml

Configure in docs.json

Add the api.openapi section to your docs.json:

{
  "api": {
    "openapi": {
      "source": "openapi.yaml",
      "directory": "api"
    }
  }
}

Deploy

Run blodemd push and your API reference pages are generated automatically at /api/{operation-id}.

Configuration options

Field	Type	Description	Required	Default
`source`	string	Path to your OpenAPI spec file, relative to the content directory.	Yes	—
`directory`	string	URL path prefix for generated API pages. Defaults to "api".	Yes	"api"
`include`	string[]	Filter which operations to include. Accepts an array of operation IDs or path patterns.	Yes	—
`basePath`	string	Override the base path for API requests in the playground.	Yes	—

You can add your OpenAPI operations directly to the navigation by referencing the spec file in a navigation group:

{
  "navigation": {
    "groups": [
      {
        "group": "API Reference",
        "openapi": "openapi.yaml"
      }
    ]
  }
}

This automatically creates navigation entries for each operation in your spec, grouped by tag.

API playground

Blode.md can render an interactive API playground alongside your documentation. Configure it with the api.playground option:

{
  "api": {
    "openapi": {
      "source": "openapi.yaml",
      "directory": "api"
    },
    "playground": {
      "display": "interactive",
      "proxy": "https://api.example.com",
      "credentials": true
    }
  }
}

Display modes

Mode	Behavior
`interactive`	Full playground with editable parameters and a "Send" button.
`simple`	Read-only display of request and response examples.
`auth`	Interactive playground that requires authentication before sending.
`none`	No playground. Only the endpoint documentation is shown.

Set credentials: true to include cookies and auth headers in playground requests. Use proxy to route requests through your backend and avoid CORS issues.

Setup

Add your spec file

Place an openapi.yaml or openapi.json file in your content directory:

docs.json

index.mdx

openapi.yaml

Configure in docs.json

Add the api.openapi section to your docs.json:

{
  "api": {
    "openapi": {
      "source": "openapi.yaml",
      "directory": "api"
    }
  }
}

Deploy

Run blodemd push and your API reference pages are generated automatically at /api/{operation-id}.

Configuration options

Field	Type	Description	Required	Default
`source`	string	Path to your OpenAPI spec file, relative to the content directory.	Yes	—
`directory`	string	URL path prefix for generated API pages. Defaults to "api".	Yes	"api"
`include`	string[]	Filter which operations to include. Accepts an array of operation IDs or path patterns.	Yes	—
`basePath`	string	Override the base path for API requests in the playground.	Yes	—

Navigation

You can add your OpenAPI operations directly to the navigation by referencing the spec file in a navigation group:

{
  "navigation": {
    "groups": [
      {
        "group": "API Reference",
        "openapi": "openapi.yaml"
      }
    ]
  }
}

This automatically creates navigation entries for each operation in your spec, grouped by tag.

API playground

Blode.md can render an interactive API playground alongside your documentation. Configure it with the api.playground option:

{
  "api": {
    "openapi": {
      "source": "openapi.yaml",
      "directory": "api"
    },
    "playground": {
      "display": "interactive",
      "proxy": "https://api.example.com",
      "credentials": true
    }
  }
}

Display modes

Mode

Behavior

interactive

Full playground with editable parameters and a "Send" button.

simple

Read-only display of request and response examples.

auth

Interactive playground that requires authentication before sending.

none

No playground. Only the endpoint documentation is shown.

Set credentials: true to include cookies and auth headers in playground requests. Use proxy to route requests through your backend and avoid CORS issues.