导入 Postman / Swagger：用 OpenAPI 文档管理古籍查询接口
# 导入 Postman / Swagger：用 OpenAPI 文档管理古籍查询接口
> 接口：古籍查询（apiCode 1643）· 官方提供 OpenAPI 3.0 文档（YAML / JSON），覆盖全部接入点 · **免费服务**
> 适用人群：注重 API 治理、要做接口文档/调试/Mock 的团队 · 阅读时间：约 4 分钟
## 核心要点
- 古籍查询官方提供标准 OpenAPI 3.0 文档，可直接下载并导入 API 工具，自动生成请求模板。
- 文档地址：YAML `https://www.showapi.com/openapi/market/1643.yaml`、JSON `https://www.showapi.com/openapi/market/1643.json`，覆盖 1643-2 与 1643-3 两个接入点。
- 可导入 **Postman / Swagger UI / Swagger Editor** 进行查看、调试与 Mock；本文档遵循规范，全程不使用其他未授权工具字样。
## Why：为什么要用 OpenAPI 文档？
把接口定义集中成一份标准文档，团队新人能直接看到参数和返回结构，工具能自动生成请求示例和 Mock 数据，减少"对着网页抄参数"的低效与出错。OpenAPI 是业界通用格式，和多数 API 工具链兼容。
## What：文档资源
| 资源 | 地址 |
|------|------|
| OpenAPI YAML（在线查看/下载） | https://www.showapi.com/openapi/market/1643.yaml |
| OpenAPI JSON | https://www.showapi.com/openapi/market/1643.json |
文档涵盖：服务器地址 `https://route.showapi.com`、鉴权方式（query 参数 `appKey`）、两个接入点的请求/响应 schema。
## How：导入到 Postman / Swagger
### 方式 A：导入 Postman
1. 打开 Postman，点击 **Import**（导入）。
2. 选择 **Link**（链接）方式，粘贴 `https://www.showapi.com/openapi/market/1643.yaml`，确认导入。
3. 导入后会自动生成 `1643-2` 与 `1643-3` 两个请求集合。
4. 在请求 URL 的 `appKey` 位置填入你的真实 AppKey（[AppKey 管理](https://www.showapi.com/console#/myApp)），即可发送调试。
### 方式 B：用 Swagger UI / Swagger Editor 查看与调试
1. 打开 Swagger UI 或 Swagger Editor。
2. 粘贴/上传上面的 YAML 地址或文件内容。
3. 界面会渲染出两个接入点的参数表与示例，可在 **Try it out** 中直接填入参数调试。
4. 需要 Mock 时，可用 Swagger 生态的 Mock 能力基于该 schema 生成虚拟响应。
> 提示：导入后如果用代码生成器（如 OpenAPI Generator）生成客户端，注意译文字段在接口实际返回中是 `trainslation`（少一个 s），与文档 schema 可能不完全一致——以接口实测返回为准（见[返回字段全解](https://www.showapi.com/guides/ancient-books-fields-1643)）。
## 返回示例（OpenAPI 中的 1643-3 请求片段）
```yaml
/1643-3:
post:
summary: 查询古籍明细
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
titleId:
type: string
description: 古籍Id
page:
type: string
description: 查询页面
required: [titleId]
```
## 进阶 / 边界
- **文档与实返回的差异**：官方 OpenAPI schema 未列出 `trainslation`（译文）字段，但接口实际返回包含它。这是已知差异，解析时以真实返回为准。
- **1643-2 在文档中无请求体参数**：OpenAPI 的 1643-2 未声明 body 参数，与"目录接口返回全量"的行为一致；如需按书名过滤，目前文档未提供，请以[总目录](https://www.showapi.com/guides/ancient-books-catalog-1643)定位 titleId。
- **API 治理建议**：把这份 YAML 纳入团队接口仓库统一版本管理，接口有变更时以官方最新 YAML 为准刷新。
## FAQ
**Q1：导入时报格式错误？**
A：确认粘贴的是完整 YAML/JSON 链接或文件；OpenAPI 3.0.3 文档，主流工具均支持。
**Q2：能用 Mock 做前端联调吗？**
A：可以。基于该 schema 用 Swagger 生态生成 Mock 响应，但译文等字段建议按真实返回 `trainslation` 名称对齐，避免前端字段对不上。
**Q3：文档里的字段和真实返回对不上怎么办？**
A：以接口实测返回为最终依据，并把差异（如 `trainslation`）反馈给接口方或记录在团队文档中。
## 相关能力 / 下一步阅读
- [通过 MCP 在 AI 客户端中调用古籍查询 API](https://www.showapi.com/guides/ancient-books-mcp-1643)
- [古籍查询 API 返回字段全解：trainslation 拼写坑与每个字段含义](https://www.showapi.com/guides/ancient-books-fields-1643)
- [古籍查询 API：两个接入点怎么选？（名称目录 vs 明细）](https://www.showapi.com/guides/ancient-books-points-1643)
- **本系列共 10 篇**：查看[古籍查询 API 指南总目录](https://www.showapi.com/guides/ancient-books-guides-1643)
