Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jamdesk/jamdesk-cli/llms.txt

Use this file to discover all available pages before exploring further.

Jamdesk can read an OpenAPI (formerly Swagger) specification and automatically generate a complete, interactive API reference — endpoint pages, request parameter tables, response schemas, and code samples — with no manual writing required. Point docs.json at your spec file, run jamdesk dev, and your API reference is live alongside the rest of your documentation. Jamdesk supports OpenAPI 3.x and Swagger 2.0, and the generated pages render in the local dev server exactly as they appear in production.

​
Setup

Add an openapi entry to your docs.json pointing at your spec file. The path can be a local file (relative to docs.json) or a public URL: 
{
  "$schema": "https://www.jamdesk.com/docs.json",
  "name": "My Docs",
  "theme": "jam",
  "openapi": "openapi.yaml",
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "groups": [
          {
            "group": "Endpoints",
            "pages": ["api-reference/list-users", "api-reference/create-user"]
          }
        ]
      }
    ]
  }
}
Individual API reference pages reference their operation via the openapi frontmatter field — Jamdesk handles the binding between your spec and the rendered page automatically.

​
Validating Your Spec

Before the dev server renders your API reference, it is worth confirming your spec is valid. The jamdesk openapi-check command validates a single spec file and reports a summary of what it found: 
jamdesk openapi-check path/to/openapi.yaml
A passing validation looks like this: 
✓ OpenAPI spec is valid
  Endpoints: 24
  Schemas: 18
  Tags: api, users, billing
The command reports:
  • Endpoints — total number of operations (path + HTTP method combinations) found in the spec.
  • Schemas — number of named component schemas defined under components/schemas.
  • Tags — the tag names used to group operations.
Any structural errors — missing required fields, invalid $ref targets, malformed parameter definitions — are reported with enough detail to locate and fix them.

​
Validate via jamdesk validate

If your docs.json already references an OpenAPI spec, jamdesk validate includes that spec in its full project check automatically. You do not need to run openapi-check separately in that case: 
jamdesk validate
This is the recommended command to run before every deployment, as it also checks MDX syntax, navigation consistency, and docs.json schema in one pass.

​
Local Preview

OpenAPI-generated pages are fully rendered in the local dev server. Start jamdesk dev as normal and navigate to the API reference section of your sidebar — request parameters, response schemas, and any examples defined in your spec are all visible and interactive without deploying to production. 
jamdesk dev
Hot reload applies to the spec file too: save a change to your openapi.yaml and the affected pages update in the browser automatically.

​
Swagger 2.0

Jamdesk supports Swagger 2.0 specs, but the openapi-check command will emit a warning when it detects one:
Swagger 2.0 is supported but deprecated. Consider upgrading your spec to OpenAPI 3.x to take advantage of improved schema features, better tooling support, and continued Jamdesk enhancements. The OpenAPI Initiative provides a converter to help with the migration.

​
Learn More

The full setup guide — including how to configure multiple specs, how to write handcrafted pages that mix prose with auto-generated parameter tables, and how to customise the layout of API reference pages — is available at jamdesk.com/docs/api-reference/openapi-setup.

Build docs developers (and LLMs) love

Get started for freeTalk to us