唐诗宋词元曲查询：导入 Postman / Swagger 用 OpenAPI 文档管理接口
唐诗宋词元曲查询OpenAPIPostmanSwaggerAPI治理 # 唐诗宋词元曲查询：导入 Postman / Swagger 用 OpenAPI 文档管理接口
> 接口：唐诗宋词元曲等诗词查询（apiCode=1620）· 免费 · 提供 OpenAPI 3.0 文档（覆盖全部接入点）· 适用：注重 API 治理的团队 · 阅读约 5 分钟
## 核心要点
- 接口官方提供标准 **OpenAPI 3.0** 文档，覆盖全部 3 个接入点，可导入 **Postman / Swagger UI** 管理与调试
- 文档地址：YAML `https://www.showapi.com/openapi/market/1620.yaml`、JSON `https://www.showapi.com/openapi/market/1620.json`
- 用 OpenAPI 文档可自动生成请求模板、做 Mock、统一团队接口契约
## Why：多人协作时，文档就是契约
当团队里有前端、后端、测试多人要对接这套诗词接口，口头传参数最容易出错。把官方 OpenAPI 文档导入 Postman 或 Swagger UI，每个人看到的都是同一份结构化定义：路径、参数、返回字段一目了然，还能一键生成请求模板做调试。对 API 治理很实用。
## What：OpenAPI 资源速览
| 项目 | 说明 |
|------|------|
| 接口编码 | 1620 |
| 文档标准 | OpenAPI 3.0 |
| 覆盖范围 | 本接口全部接入点（1620-3 / 1620-4 / 1620-5） |
| YAML 地址 | `https://www.showapi.com/openapi/market/1620.yaml` |
| JSON 地址 | `https://www.showapi.com/openapi/market/1620.json` |
| 用途 | 导入 Postman / Swagger UI、生成请求模板与 Mock、AI Agent 直接消费 |
## How：导入 Postman / Swagger UI
### 步骤 1 · 获取文档
直接下载或在线查看：
```bash
# 下载 YAML
curl -O "https://www.showapi.com/openapi/market/1620.yaml"
# 或下载 JSON
curl -O "https://www.showapi.com/openapi/market/1620.json"
```
### 步骤 2 · 导入 Postman
1. 打开 Postman → 左上角 `Import`。
2. 选择「Link」或「File」，粘贴/选择上面下载的 `1620.yaml` 或 `1620.json`。
3. 导入后 Postman 会自动生成各接入点的请求集合（含路径、参数定义）。
4. 在请求的 `appKey` 参数处填入你的真实 AppKey（[AppKey 管理](https://www.showapi.com/console#/myApp)），即可发送调试。
### 步骤 3 · 导入 Swagger UI
1. 打开 Swagger UI（自建或用官方/第三方托管实例）。
2. 在顶部的 `Explore` / `URL` 输入框填入 `https://www.showapi.com/openapi/market/1620.yaml`。
3. 加载后可在页面内展开每个接入点，填写参数并「Try it out」直接调试。
**用文档生成请求的示意（Python 读取 paths 生成 URL）**
```python
import yaml, requests
# 读取本地 OpenAPI 文档，提取 1620-3 的路径与参数（示意）
spec = yaml.safe_load(open("1620.yaml", encoding="utf-8"))
path = spec["paths"].get("/1620-3") # 具体路径以文档为准
print("1620-3 定义:", path)
APP_KEY = "YOUR_APPKEY"
r = requests.post("https://route.showapi.com/1620-3",
params={"appKey": APP_KEY},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=10)
print(r.json().get("showapi_res_body", {}).get("dynastyInfo", [])[:3])
```
## 返回示例与解析
OpenAPI 文档本身是结构化 YAML/JSON，描述的是接口契约（路径、参数、响应 schema）。导入工具后，你看到的仍是真实调用返回的 `showapi_res_body`（朝代/诗人/诗词字段），文档只负责「定义」，数据仍来自接口。
## 进阶 / 边界
- **文档与代码一致**：OpenAPI 是官方给出的契约，团队应以它为准对齐前后端字段命名（如 `dynastyInfo` / `poetInfo` / `contentlist` 均为数组）。
- **Mock 调试**：在 Postman/Swagger 中可基于 schema 生成 Mock 响应，前端可在接口未稳定时并行开发。
- **AI Agent 消费**：OpenAPI 文档可被 AI 工具直接读取，结合本接口的 MCP 服务，形成「文档治理 + Agent 调用」双路径。
- **参数为空注意**：OpenAPI 描述的是全量接入点，单个接入点（如 1620-3）可能无业务参数，导入后该请求只需 `appKey`。
## FAQ
**Q1：导入后为什么有些接入点没有业务参数？**
正常。例如「查询朝代列表」（1620-3）按文档无需业务参数，只有 `appKey` 鉴权；其他接入点（1620-4/1620-5）才有 `dynastyId` / `poet` / `title` 等参数。
**Q2：YAML 和 JSON 选哪个导入？**
两者内容等价，Postman/Swagger UI 都支持。团队习惯用 YAML（可读性好）或 JSON（易程序解析）皆可。
**Q3：OpenAPI 文档会随接口更新吗？**
以官方提供的文档地址为准；若接口有变更，建议重新拉取最新文档并同步到团队工具中。
**Q4：能根据文档自动生成代码吗？**
OpenAPI 生态有大量代码生成器（如 openapi-generator），可基于该文档生成多语言 SDK 骨架；生成后填入 `appKey` 与地址即可使用。
## 相关能力 / 下一步阅读
- [唐诗宋词元曲查询：通过 MCP 协议在 Cherry Studio / ChatBox 中直接查诗词](https://www.showapi.com/guides/poem-mcp-1620) — 另一条生态路径：AI Agent 直接调用
- [唐诗宋词元曲查询返回结构全解：ret_code、dynastyInfo、poemInfo 一文读懂](https://www.showapi.com/guides/poem-response-fields-1620) — 对照文档核对字段
- **本系列共 12 篇**：查看[唐诗宋词元曲查询指南总目录](https://www.showapi.com/guides/poem-guides-1620)
