OpenAPI Example

POSThttps://jamdesk-docs.jamdesk.app/api/playground/demo/tickets

Create a new ticket for a customer issue or request.

Loading code example

Loading code example

Body

customer_idstringrequired

Customer identifier in Acme.

subjectstringrequired

Short summary of the issue.

priority"low" | "normal" | "high" | "urgent"

Allowed values: "low" | "normal" | "high" | "urgent"

tagsarray<string>

messagestringrequired

Detailed problem description.

Response

application/json

Ticket created

idstring

customer_idstring

subjectstring

prioritystring

status"open" | "pending" | "resolved"

Allowed values: "open" | "pending" | "resolved"

tagsarray<string>

messagestring

created_atstring<date-time>

updated_atstring<date-time>

This page demonstrates a live endpoint generated from an OpenAPI specification. The request schema, response models, and code examples in the right panel are all auto-generated from the spec, with no manual authoring required.

This example uses the Acme Support API. Update api.openapi in your docs.json to point at your own spec file to generate real endpoints.

Multi-language docs? Provide a <spec>.<lang>.<ext> file next to your source spec (e.g., example-api.fr.yaml) and Jamdesk renders the translated version when users view the page under /fr/.... See Translating OpenAPI Specs.

This page has the API Playground enabled. Click Try it on the endpoint above to test the API live.

What Gets Generated

From a single openapi frontmatter line, Jamdesk auto-generates:

An endpoint badge showing the method and path with color coding
Parameter documentation for path, query, header, and body parameters
Request and response schemas, including nested objects and arrays
Code examples in cURL, Python, JavaScript, Go, Ruby, C#, Java, Rust, and PHP (configurable via api.examples.languages)
Authentication details pulled from the spec's security schemes

All $ref references in your spec are automatically resolved, so you can organize schemas with components/schemas as usual.

Descriptions in your spec are rendered as Markdown, not printed as raw text — operation, parameter, request-body, response, and schema descriptions all support the same bold, code, lists, links, and GFM tables you would write in an .mdx page.

Setting Up OpenAPI

Place your OpenAPI 3.x spec (YAML or JSON) in the openapi/ directory, register it in docs.json under api.openapi, then add openapi: /openapi/your-spec.yaml METHOD /path to any page's frontmatter. See the OpenAPI setup guide for full details.

Generate a Page for Every Operation

Rather than authoring one page per endpoint, point a navigation tab at the spec and let Jamdesk build the whole reference:

docs.json

{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "openapi": { "source": "/openapi/api.yaml", "generate": true }
      }
    ]
  }
}

Every operation gets a page and the sidebar is grouped by tag. Committed .mdx files win on slug collision, so you can adopt this a page at a time, and renaming a path in your spec redirects the old URL instead of breaking it. See navigation openapi for the full rules and current limits.

Writing your spec in YAML? Run it through the free YAML Validator to catch indentation and syntax errors before the build parses it.

API Playground

Enable interactive API testing on your endpoint pages

Request/Response Examples

Hand-authored endpoint example using MDX components

OpenAPI Setup

Where to store and reference OpenAPI files

docs.json Reference

Full configuration reference including api.openapi