银行汇率查询 OpenAPI 文档：导入 Postman 与 Swagger UI
约 10 分钟 进阶银行汇率查询OpenAPIPostmanSwagger UI
# 银行汇率查询 OpenAPI 文档：导入 Postman 与 Swagger UI
接口：银行汇率查询（apiCode=105）· 集成能力：OpenAPI 3.0（覆盖全部 4 个接入点）· 免费接口（L0 基础版 100 次/天、1 QPS）· 适用人群：做接口治理、团队协作与自动化测试的开发者 · 阅读时间：约 5 分钟 · 最后实测核对：2026-09-18
## 核心要点
- 官方提供标准 OpenAPI 3.0 文档，YAML 与 JSON 两个版本，覆盖 105-30 / 31 / 34 / 35 四个接入点。
- 文档里带了页面上看不到的信息：`x-read-timeout`、`x-connect-timeout`、`x-pointCode`、`externalDocs`。
- 导入 Postman 或 Swagger UI 后，把 `appKey` 放进环境变量，就能直接发请求、做 Mock、写测试。
## 一份文档解决参数靠猜
团队接手一个接口，最耗时的一步往往是确认参数与返回结构。四个接入点的路径、参数、响应 schema 都写在官方 OpenAPI 文档里，把它导进你已经在用的 API 工具，请求模板、环境变量、测试用例都可以从同一份定义生成。以后接口有改动，重新拉一次文档做 diff 就能看出差异。
## 文档入口与基本信息
| 项目 | 说明 |
|------|------|
| YAML 地址 | `https://www.showapi.com/openapi/market/105.yaml` |
| JSON 地址 | `https://www.showapi.com/openapi/market/105.json` |
| 规范版本 | `openapi: 3.0.3` |
| 接口标题 | 银行汇率查询 |
| 文档版本 | `1.0.0` |
| 覆盖路径 | `/105-30`、`/105-31`、`/105-34`、`/105-35` |
| 服务地址 | `https://route.showapi.com` |
| 鉴权方式 | `AppKeyAuth`，类型 `apiKey`，位置 `query`，参数名 `appKey` |
| 适用工具 | Postman、Swagger UI、Swagger Editor，以及支持 OpenAPI 3.0 的代码生成器 |
2026-09-18 实测两个地址都可直接访问，JSON 版本可以整体 `JSON.parse`，适合用脚本读取做自动化校验。
## 文档里页面上看不到的字段
接口文档页展示的是参数与返回字段，OpenAPI 文档还多带了几项信息：
| 字段 | 位置 | 含义 |
|------|------|------|
| `x-pointCode` | 每个 path 下 | 接入点编号，例如 `/105-30` 的 `x-pointCode` 是 `30` |
| `x-mode` | 每个 path 下 | 调用模式，四个接入点均为 `mapping` |
| `x-read-timeout` | 每个 path 下 | 读超时，105-30 / 31 / 34 为 15 秒，105-35 为 30 秒 |
| `x-connect-timeout` | 每个 path 下 | 连接超时，取值与读超时一致 |
| `externalDocs.url` | 文档根级 | 指向接口的在线调试与文档入口 |
| `x-apiCode` | 文档根级 | 接口编号，值为 `105` |
| `components.schemas.ShowapiResEnvelope` | 文档根级 | 统一返回信封的 schema：`showapi_res_code`、`showapi_res_error`、`showapi_res_id`、`showapi_fee_num` |
超时这两个值在接口文档页上没有展示，只在 OpenAPI 文档里能读到。客户端超时设置建议直接对齐这两个值，尤其是调用币种列表（105-35）时——它的超时是其他接入点的两倍。
文档根级还带一行生成信息，可以据此判断手上这份文档的新鲜度：
```yaml
# Generated by ShowAPI OpenAPI generator
# source: market/105
# generated-at: 2026-09-17T05:32:12.451Z
```
## 导入 Postman
在 Postman 里选择 Import，把 YAML 内容粘贴进去或上传文件，导入完成后会出现四个请求定义。接着建一个环境变量保存 AppKey，在请求的 query 里引用它：
```
变量名：showapi_appkey
当前值：你的真实 AppKey
```
请求地址写成 `https://route.showapi.com/105-30?appKey={{showapi_appkey}}`。这样切环境时不用改请求本身，也不会把 Key 写死在集合里。
四个接入点的请求体可以直接照抄文档的 `requestBody`：
| 路径 | 请求体（`application/x-www-form-urlencoded`） |
|------|-----------------------------------------------|
| `/105-30` | `code`（可选，货币缩写，不传返回全部） |
| `/105-31` | `fromCode`、`toCode`、`money`（三个都必填） |
| `/105-34` | `code` 或 `name`（至少一个）、`month` 或 `startDate` + `endDate` |
| `/105-35` | 无业务参数 |
## 导入 Swagger UI 或 Swagger Editor
Swagger UI 与 Swagger Editor 都兼容 OpenAPI 3.0。在 Swagger UI 的配置里把 `url` 指向 `https://www.showapi.com/openapi/market/105.yaml`，页面会渲染出四个接入点的接口列表，可以直接在「Try it out」里填参数发请求，省去写代码这一步。
在 Swagger Editor 里粘贴 YAML 内容，右侧会实时显示解析结果，改错格式时能立刻看到校验提示，适合在提交前自查。
## 放进仓库做版本留档
把 YAML 存进代码仓库，每次接口变更重新拉取并 diff，改动会体现在字段名、枚举、超时值这些行上。这项留档对 CI 里的冒烟测试也有用：用文档定义的响应 schema 校验真实返回，字段被删或被改名时测试会直接失败，而不是等到线上才发现。
```bash
# 用官方文档页的下载入口保存到仓库目录，再对比差异
# 保存路径：openapi/105.yaml
git diff --stat openapi/105.yaml
```
## FAQ
**Q1：OpenAPI 和 MCP 该用哪个？**
用途不同。OpenAPI 面向接口治理、团队协作、自动化测试；MCP 面向在 AI 客户端里对话式调用。两者底层都是同一套接口，可以同时使用。
**Q2：文档会跟着接口更新吗？**
文档根级带 `generated-at` 时间戳，可以据此判断手上的版本新旧。团队定期重新拉取并做 diff 即可。
**Q3：能导入 Swagger UI 吗？**
能。只要工具兼容 OpenAPI 3.0 就能导入，Swagger UI 与 Swagger Editor 都在文档标注的支持列表内。
**Q4：文档里为什么没有 `required` 数组？**
`/105-31` 的 `requestBody.schema` 里带 `required: [fromCode, toCode, money]`；其他接入点的必填规则写在参数描述文字里，例如 `/105-34` 的时间参数互斥关系。导入工具后建议把这层规则也写进团队的检查清单。
**Q5：生成请求模板时 `appKey` 怎么处理？**
OpenAPI 里 `appKey` 是 query 位置的 `apiKey` 占位，导入后替换成真实值。建议用工具的环境变量或密钥管理功能，不要硬编码在请求里。
## 下一步阅读
- [银行汇率查询：用 MCP 在 AI 客户端里对话式查汇率](https://www.showapi.com/guides/exchange-rate-mcp-105)：另一条集成路径与实测握手过程。
- [银行汇率查询返回字段全解（五大价位 / 两层状态码 / 空值情况）](https://www.showapi.com/guides/exchange-rate-fields-105)：响应 schema 对应的字段含义。
- [银行汇率查询：5 分钟从注册跑到第一次调用](https://www.showapi.com/guides/exchange-rate-quickstart-105)：导入之后第一次发请求要带什么参数。
- **本系列共 13 篇**：查看[银行汇率查询指南总目录](https://www.showapi.com/guides/exchange-rate-guides-105)
