CamelMind

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

Before you begin

You'll need an OpenAPI 3.x specification in either YAML or JSON format.

For example:

text

openapi/
└── openapi.yaml

Enable the interactive OpenAPI reference

To enable the interactive API reference in CamelMind:

Configure your OpenAPI specifications in camelmind.config.ts.
Associate an API specification with each documentation version in versions.yml.

Configure your API specifications

Open camelmind.config.ts and enable the API Reference.

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

    navLabel: "API Reference",

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

This registers the available OpenAPI specifications for your documentation site.

Associate a spec with a documentation version

Open versions.yml and specify which API specification should be displayed for each version.

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:

yaml

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.

See it in action

This documentation site registers two OpenAPI specifications—main and partner—and publishes them as tabs in the same API Reference page: REST API and Partner API.

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.

Note

Role restrictions apply to the entire API reference. You cannot currently restrict individual endpoints independently.

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:

yaml

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:

Field	Description
`enabled`	Enables the API Reference.
`navLabel`	Text displayed in the top navigation. Default: `API Reference`.
`specs`	One or more OpenAPI specifications to publish.
`languages`	Languages shown for generated code samples.
`roles`	Roles required to access the API Reference. Empty (`[]`) makes it public.

Supported OpenAPI specification formats

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

Example OpenAPI 3.1 specification:

yaml

openapi: "3.1.0"

info:
  title: My API
  version: "1.0.0"

paths:
  /users:
    get:
      summary: List users

Note

The offline package includes the fully rendered API Reference for the downloaded documentation version. Any API references that are accessible on the live site are included in the offline package, allowing you to browse endpoints, request and response schemas, and code samples without signing in or connecting to the internet.