OpenAPI 示例
查看基于 OpenAPI 自动生成的 endpoint 页面，了解 Jamdesk 如何直接从 spec 渲染请求、响应和身份验证。
POST
Create a new ticket for a customer issue or request.
Body
customer_idstringrequiredCustomer identifier in Acme.
subjectstringrequiredShort summary of the issue.
priority"low" | "normal" | "high" | "urgent"Allowed values:
"low" | "normal" | "high" | "urgent"tagsarray<string>messagestringrequiredDetailed problem description.
Response
application/json
Ticket created
idstringcustomer_idstringsubjectstringprioritystringstatus"open" | "pending" | "resolved"Allowed values:
"open" | "pending" | "resolved"tagsarray<string>messagestringcreated_atstring<date-time>updated_atstring<date-time>本页展示了基于 OpenAPI specification 自动生成的实时 endpoint。右侧面板中的请求 schema、响应模型和代码示例都是从 spec 自动生成的——无需手动编写。
本示例使用 Acme Support API。将 docs.json 中的 api.openapi 指向你自己的 spec 文件，即可生成真实的 endpoint。
本页启用了 API playground——点击上方 endpoint 的 Try it 即可实时测试 API。
自动生成的内容
只需在 frontmatter 中添加一行 openapi，Jamdesk 会自动生成：
- Endpoint 徽章 —— 方法和路径，带颜色标识
- 参数文档 —— path、query、header 和 body 参数
- 请求/响应 schema —— 包含嵌套对象和数组
- 代码示例 —— cURL、Python、JavaScript、Go、Ruby、C#、Java、Rust、PHP（可通过
api.examples.languages配置） - 身份验证详情 —— 从 spec 的 security schemes 中提取
spec 中的所有 $ref 引用都会自动解析，因此你可以像往常一样使用 components/schemas 组织 schema。
OpenAPI 设置
将 OpenAPI 3.x spec（YAML 或 JSON）放入 openapi/ 目录，在 docs.json 的 api.openapi 下注册，然后在任意页面的 frontmatter 中添加 openapi: /openapi/your-spec.yaml METHOD /path。完整说明请参阅 OpenAPI 设置指南。