OpenAPI 示例

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>

本页面是由 OpenAPI 规范生成的实时端点。Jamdesk 根据该规范在右侧面板中生成请求架构、响应模型和代码示例。

本示例使用 Acme Support API。请在 docs.json 中将 api.openapi 指向您的规范文件，以生成您的端点。

多语言文档？ 请在源规范文件旁边提供 <spec>.<lang>.<ext> 文件（例如 example-api.fr.yaml）。Jamdesk 会在 /fr/... 下的页面中呈现翻译版本。请参阅翻译 OpenAPI 规范。

本页面已启用 API Playground。点击上方端点的 Try it 即可实时测试该 API。

生成的内容

仅需一行 openapi frontmatter，Jamdesk 即可生成：

带颜色编码的端点徽章，显示请求方法和路径
路径、查询、请求头和请求体参数的文档
请求和响应架构，包括嵌套对象和数组
cURL、Python、JavaScript、Go、Ruby、C#、Java、Rust 和 PHP 的代码示例（可通过 api.examples.languages 配置）
从规范的安全方案中提取的身份验证详情

Jamdesk 会解析规范中的每个 $ref。像往常一样，使用 components/schemas 组织架构。

Jamdesk 会将规范中的描述渲染为 Markdown，而非原始文本。操作、参数、请求体、响应和架构的描述支持您在 .mdx 页面中使用的同样的粗体、代码、列表、链接和 GFM 表格。

设置 OpenAPI

将您的 OpenAPI 3.x 规范（YAML 或 JSON）放置在 openapi/ 目录中。在 docs.json 的 api.openapi 下注册该规范。然后在任意页面的 frontmatter 中添加 openapi: /openapi/your-spec.yaml METHOD /path。完整详情请参阅 OpenAPI 设置指南。

为每个操作生成页面

将导航标签页指向规范，即可让 Jamdesk 自动生成完整的参考文档，无需为每个端点单独编写页面：

docs.json

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

每个操作都会生成一个页面。侧边栏按标签分组。已提交的 .mdx 文件在 slug 冲突时优先。您可以逐页采用此功能。在规范中重命名路径会将旧 URL 重定向，而不是导致链接失效。完整规则和当前限制请参阅 navigation openapi。

使用 YAML 编写规范？可通过免费的 YAML 验证器在构建解析前检查缩进和语法错误。