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 is a live endpoint generated from an OpenAPI specification. Jamdesk generates the request schema, response models, and code examples in the right panel from the spec.

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

Multi-language docs? Provide a <spec>.<lang>.<ext> file next to your source spec (e.g., example-api.fr.yaml). Jamdesk renders the translated version on pages 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 one openapi frontmatter line, Jamdesk 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

Jamdesk resolves every $ref in your spec. Organize schemas with components/schemas as usual.

Jamdesk renders descriptions in your spec as Markdown, not raw text. Operation, parameter, request-body, response, and schema descriptions take 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

Point a navigation tab at the spec to have Jamdesk build the whole reference, instead of writing one page per endpoint:

docs.json

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

Every operation gets a page. The sidebar is grouped by tag. Committed .mdx files win on slug collision. You can adopt this one page at a time. 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