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 interactive OpenAPI reference

To enable the interactive API reference in CamelMind:

1. Configure your OpenAPI specifications in camelmind.config.ts.
2. Associate an API 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: "latest"
    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.

First, register each spec in camelmind.config.ts:

apiReference: {
  enabled: true,

  navLabel: "API Reference",

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

Then configure the tabs for each documentation version in versions.yml:

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

    api_reference:
      tabs:
        - id: main
          spec: main

        - id: partner
          spec: partner

Each tab's spec value must match one of the specification IDs defined in apiReference.specs.

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

Customize API reference code sample languages

To specify which programming languages appear in the generated API reference code samples, configure the languages array in camelmind.config.ts:

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

By default, CamelMind displays code samples for:

• curl
• JavaScript
• Python

Restrict API reference access with user roles

To restrict access to the API reference, specify the required user roles in camelmind.config.ts:

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

When you leave roles empty ([]), CamelMind allows public access to the entire API reference.

Use different API specs for each documentation version

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

First, register each version's spec in camelmind.config.ts:

apiReference: {
  enabled: true,

  specs: {
    v2: {
      label: "API v2",
      file: "openapi/v2.yaml",
    },
    v1: {
      label: "API v1",
      file: "openapi/v1.yaml",
    },
  },
},

Then reference the matching spec ID for each version in versions.yml:

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

    api_reference:
      spec: v2

  - id: v1
    label: v1
    nav: nav/nav-v1.yml

    api_reference:
      spec: v1

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

API reference configuration options

Use these configuration options in camelmind.config.ts to customize your API reference settings:

Supported OpenAPI specification formats

CamelMind supports OpenAPI 3.x specifications in both YAML and JSON formats.

Example OpenAPI 3.1 specification:

openapi: "3.1.0"

info:
  title: My API
  version: "1.0.0"

paths:
  /users:
    get:
      summary: List users