---
title: OpenAPI 示例
description: 查看实时的 OpenAPI 生成端点页面，了解 Jamdesk 如何直接根据规范呈现请求、响应和身份验证。
openapi: /openapi/example-api.yaml POST /tickets
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

此页面展示了一个由 [OpenAPI 规范](https://spec.openapis.org/oas/latest.html)生成的实时端点。右侧面板中的请求架构、响应模型和代码示例均根据规范自动生成，无需手动编写。

<Info>
此示例使用 Acme Support API。更新 `docs.json` 中的 `api.openapi`，指向你自己的规范文件，即可生成真实端点。
</Info>

<Info>
**多语言文档？** 在源规范文件旁放置一个 `<spec>.<lang>.<ext>` 文件（例如 `example-api.fr.yaml`），用户通过 `/fr/...` 查看页面时，Jamdesk 会呈现翻译后的版本。请参阅[翻译 OpenAPI 规范](/cn/setup/languages#翻译-openapi-规范)。
</Info>

<Tip>
此页面已启用 [API Playground](/cn/api-reference/playground)。点击上方端点中的 **Try it**，即可在线测试 API。
</Tip>

## 生成的内容

只需一行 `openapi` frontmatter，Jamdesk 就会自动生成：

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

规范中的所有 `$ref` 引用都会自动解析，因此你可以像往常一样使用 `components/schemas` 组织架构。

## 设置 OpenAPI

将 OpenAPI 3.x 规范（YAML 或 JSON）放入 `openapi/` 目录，在 `docs.json` 的 `api.openapi` 下注册该规范，然后将 `openapi: /openapi/your-spec.yaml METHOD /path` 添加到任意页面的 frontmatter 中。详细信息请参阅 [OpenAPI 设置指南](/cn/setup/directory-structure#openapi)。

<Tip>
  使用 YAML 编写规范？通过免费的 [YAML Validator](https://jamdesk.com/utilities/yaml-validator) 检查规范，在构建解析前发现缩进和语法错误。
</Tip>

## 相关页面

<Columns cols={2}>
  <Card title="API Playground" icon="flask-vial" href="/cn/api-reference/playground">
    在端点页面启用交互式 API 测试
  </Card>
  <Card title="请求/响应示例" icon="code" href="/cn/api-reference/request-response-examples">
    使用 MDX 组件手动编写的端点示例
  </Card>
</Columns>

<Columns cols={2}>
  <Card title="OpenAPI 设置" icon="file-code" href="/cn/setup/directory-structure#openapi">
    OpenAPI 文件的存储和引用位置
  </Card>
  <Card title="docs.json 参考" icon="file-lines" href="/cn/config/docs-json-reference">
    包含 api.openapi 的完整配置参考
  </Card>
</Columns>

---

📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://jamdesk-docs.jamdesk.app/api-specs.zip