节假日查询：导入 Postman / Swagger，用 OpenAPI 文档管理接口
# 节假日查询：导入 Postman / Swagger，用 OpenAPI 文档管理接口
> 接口 894（全部接入点，经 OpenAPI 3.0 封装） · 免费 · OpenAPI 3.0 · 适用人群：API 治理团队 · 阅读时间：约 6 分钟
## TL;DR
- 节假日查询提供标准 **OpenAPI 3.0** 文档，覆盖全部 3 个接入点。
- 下载 YAML/JSON 导入 API 工具（如 Postman、Swagger UI），自动生成请求模板与 Mock。
- 文档可被 AI Agent 直接消费，利于 API 治理与团队复用。
## Why：用标准文档管理接口
团队接多个接口时，散落的 curl 片段很难维护。OpenAPI 文档是行业标准的"接口契约"：导入工具即可生成可调用的请求模板、Mock Server，也能让代码生成器/AI Agent 直接读懂接口结构。
## What：OpenAPI 文档地址（来自官方）
| 格式 | 地址 |
|------|------|
| YAML（在线/下载） | `https://www.showapi.com/openapi/market/894.yaml` |
| JSON | `https://www.showapi.com/openapi/market/894.json` |
文档含 894-4 / 894-6 / 894-7 三个 path，每个带参数定义与响应 schema（与前面各接入点指南一致）。
## How：导入并使用
### 步骤 1：下载文档
```bash
curl -O https://www.showapi.com/openapi/market/894.yaml
```
### 步骤 2：导入 API 工具
- **Postman**：Import → 选择 `894.yaml` → 自动生成 3 个请求的 Collection，补全 `appKey` 即可发送。
- **Swagger UI / Swagger Editor**：粘贴 YAML，界面直接展示参数表单与示例响应，可在线调试。
- **AI Agent**：把 YAML 作为上下文喂给支持 OpenAPI 的 Agent，使其理解参数与返回结构后自动调用。
### 步骤 3：生成 Mock / 客户端
多数支持 OpenAPI 的工具可据此一键生成：
- Mock Server（返回 schema 结构，便于前端并行开发）；
- 各语言客户端 SDK（如 openapi-generator）。
## 返回示例与解析
OpenAPI 文档里 `showapi_res_body` 的 schema 定义了各接入点字段，例如 894-6 的 `type` 枚举（`1`/`2`/`3`）、`h` 数组结构等，与 [返回字段全解](https://www.showapi.com/guides/holiday-query-response-codes-894) 完全对应。
## 进阶 / 边界
- **文档即契约**：以官方 OpenAPI 为准，团队内部分流改动应基于它，避免各写各的。
- **鉴权在 query**：文档中 `appKey` 以 apiKey-in-query 方式声明，导入工具会自动带上鉴权位。
- **Mock 仅结构**：Mock Server 返回的是 schema 形状，不是真实数据，联调仍需调真实接口。
## FAQ
**Q1：YAML 和 JSON 选哪个？**
A：功能等价。Postman/Swagger 多认 YAML；程序化消费可用 JSON。
**Q2：文档会和实际接口不一致吗？**
A：官方维护，一般与接口同步；若发现偏差以接口实际返回为准。
**Q3：能生成 SDK 吗？**
A：可用 openapi-generator 等工具基于该文档生成多语言客户端。
**Q4：和 MCP 比哪个好？**
A：MCP 适合 AI Agent 实时调用；OpenAPI 适合团队 API 治理与代码生成。两者可并行。
**Q5：文档覆盖全部接入点吗？**
A：是，894-4 / 894-6 / 894-7 全部包含。
## 相关能力 / 下一步阅读
- [节假日查询：通过 MCP 协议在 AI 客户端里直接调用](https://www.showapi.com/guides/holiday-query-mcp-894)
- [节假日查询返回字段全解：ret_code 与 type(1/2/3) 及三接入点结构一文读懂](https://www.showapi.com/guides/holiday-query-response-codes-894)
- [节假日查询：5 分钟接入，从注册到拿到全年放假安排](https://www.showapi.com/guides/holiday-query-quickstart-894)
- **本系列共 12 篇**：查看[节假日查询指南总目录](https://www.showapi.com/guides/holiday-query-guides-894)
