Skip to content
Blode.md

AI agents: fetch the documentation index at llms.txt. Markdown versions are available by appending .md to any page URL, including this page's markdown.

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

FieldTypeDescriptionRequiredDefault
sourcestringPath to your OpenAPI spec file, relative to the content directory.Yes—
directorystringURL path prefix for generated API pages. Defaults to "api".Yes"api"
includestring[]Filter which operations to include. Accepts an array of operation IDs or path patterns.Yes—
basePathstringOverride 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.your-domain.test",
      "credentials": true
    }
  }
}

Display modes

ModeBehavior
interactiveFull playground with editable parameters and a "Send" button.
simpleRead-only display of request and response examples.
authInteractive playground that requires authentication before sending.
noneNo playground. Only the endpoint documentation is shown.