API Reference

CamelMind can generate a fully interactive API reference from an OpenAPI 3.x specification. Once enabled, your API reference is automatically added to the top navigation and stays in sync with your documentation.

Features include:

• Interactive endpoint documentation
• Built-in request and response examples
• Multi-language code samples
• Support for multiple OpenAPI specifications
• Role-based access control
• Version-specific API references

openapi/
└── openapi.yaml

Enable the API reference

Enabling the API Reference requires two steps:

1. Configure one or more OpenAPI specifications in camelmind.config.ts.
2. Associate a specification with each documentation version in versions.yml.

const config: CamelMindConfig = {
  apiReference: {
    enabled: true,

    navLabel: "API Reference",

    specs: {
      main: {
        label: "REST API",
        file: "openapi/openapi.yaml",
      },
    },
  },
}

versions:
  - id: "v2"
    label: "Latest"
    stable: true
    nav: nav/nav.yml

    api_reference:
      spec: main

Add multiple API specifications

If your documentation includes multiple APIs—for example, a public API and a partner API—you can publish multiple OpenAPI specifications as tabs within the same API Reference.

Configure the tabs for each documentation version in versions.yml:

versions:
  - id: "v1"
    label: "v1"
    stable: true
    nav: nav/nav-v1.yml

    api_reference:
      tabs:
        - id: main
          spec: main-api

        - id: partner
          spec: partner-api

Each tab references a spec defined in apiReference.specs in camelmind.config.ts.

The spec value must match one of the configured specification IDs.

When users open the API Reference, they can switch between the available API specifications using the tabs at the top of the page.

Customize code samples

Choose which languages appear in the generated examples.

apiReference: {
  languages: [
    "curl",
    "javascript",
    "python",
  ],
}

By default CamelMind displays:

• curl
• JavaScript
• Python

Restrict access

To make the API reference available only to specific users, configure the required roles.

apiReference: {
  roles: [
    "developer",
    "admin",
  ],
}

If roles is empty ([]), the API reference is publicly accessible.

Use different API specs for each documentation version

If your documentation uses versioning, each version can display its own OpenAPI specification.

versions:
  - id: v2
    label: v2 (Latest)

    apiSpec:
      label: API v2
      file: openapi/v2.yaml

  - id: v1
    label: v1

    apiSpec:
      label: API v1
      file: openapi/v1.yaml

When users switch documentation versions, CamelMind automatically loads the corresponding API specification.

Configuration reference

Supported specification format

CamelMind supports OpenAPI 3.x specifications in either YAML or JSON format.

Example:

openapi: "3.1.0"

info:
  title: My API
  version: "1.0.0"

paths:
  /users:
    get:
      summary: List users