字典查询：导入 Postman / Swagger，用 OpenAPI 文档管理你的接口
字典查询OpenAPIPostmanSwagger # 字典查询：导入 Postman / Swagger，用 OpenAPI 文档管理你的接口
> 元信息：接口 **字典查询**（apiCode 1524）· 免费服务 · 提供 OpenAPI 3.0 文档 · 适用：注重 API 治理的团队、后端工程师 · 阅读时间约 6 分钟
## 核心要点
- 字典查询提供标准 OpenAPI 3.0 文档（YAML/JSON），覆盖全部 6 个接入点，可直接导入 API 工具管理。
- 文档地址：YAML `https://www.showapi.com/openapi/market/1524.yaml`、JSON `https://www.showapi.com/openapi/market/1524.json`。
- 导入后自动生成请求模板与 Mock 数据，便于团队协作、联调与契约测试。
## Why：为什么用 OpenAPI 文档管理接口
当字典查询被多个服务、多个开发者共用时，口头约定接口容易出错。OpenAPI 文档是一份机器可读的「契约」：导入 Postman / Swagger UI 后，团队成员无需翻文档就能拿到正确的请求结构，还能一键发请求、看 Mock，联调效率大幅提升。
## What：前置条件与接口速览
| 项 | 值 |
|----|----|
| 接口 | 字典查询 1524 |
| OpenAPI 文档 | YAML：`https://www.showapi.com/openapi/market/1524.yaml` |
| | JSON：`https://www.showapi.com/openapi/market/1524.json` |
| 覆盖范围 | 全部 6 个接入点（1524-1 ~ 1524-6） |
| 适用工具 | Postman、Swagger UI、Swagger Editor 等支持 OpenAPI 3.0 的工具 |
接口详情页：[https://www.showapi.com/apiGateway/view/1524](https://www.showapi.com/apiGateway/view/1524)
## How：导入并管理
### 步骤 1：下载 / 打开 OpenAPI 文档
```bash
curl -O "https://www.showapi.com/openapi/market/1524.yaml"
```
### 步骤 2：导入 Postman
1. 打开 Postman，选择「Import」。
2. 选择刚下载的 `1524.yaml`（或贴 JSON 地址）。
3. 导入后自动生成 6 个接入点的请求集合，含路径、参数与示例。
4. 在请求 URL 的 `appKey` 处填入你的 AppKey（[控制台](https://www.showapi.com/console#/myApp)获取），即可发送。
### 步骤 3：用 Swagger UI 在线预览
1. 打开 Swagger UI / Swagger Editor。
2. 粘贴 `https://www.showapi.com/openapi/market/1524.yaml` 内容或地址。
3. 界面列出全部接入点，可直接「Try it out」填入参数（如 `hanzi=你`）并查看响应结构。
### 步骤 4：在代码中消费契约（示例：用 openapi-spec-validator 做校验）
```python
# 团队 CI 中校验本地实现是否偏离契约
from openapi_spec_validator import validate_spec
import yaml, requests
spec = yaml.safe_load(requests.get("https://www.showapi.com/openapi/market/1524.yaml").text)
validate_spec(spec) # 契约合法则通过，否则 CI 报错
```
## 返回示例与字段解析
OpenAPI 文档已包含每个接入点的请求参数与响应结构定义。业务响应字段（如 `showapi_res_body` 内的 `ret_code`、各接入点字段）详见[字典查询：返回字段全解](https://www.showapi.com/guides/dict-response-codes-1524)。
## 进阶 / 边界
- **AppKey 不要入库**：OpenAPI 文档是公开契约，但 `appKey` 是私密凭证，仅运行时注入，切勿提交到代码仓库。
- **契约与实现一致性**：若你基于契约生成 Mock 或客户端，定期重新拉取官方 YAML，避免因接口更新而脱节。
- **Mock 仅用于联调**：Mock 数据来自契约示例，不等于真实返回，上线前务必用真实 AppKey 跑通。
## FAQ
**Q1：导入后还需要自己写请求代码吗？**
Postman 已生成可发送的请求模板；若要写业务代码，可基于契约用代码生成器产出 SDK，或参考[5 分钟接入](https://www.showapi.com/guides/dict-quickstart-1524)的 Python/cURL/Node.js 示例。
**Q2：OpenAPI 文档覆盖全部接入点吗？**
是的，官方 YAML/JSON 覆盖 1524-1 ~ 1524-6 全部 6 个接入点。
**Q3：团队怎么做接口联调？**
把 YAML 提交到团队仓库，Postman 集合共享，前端用 Mock 先行开发，后端用真实 AppKey 联调，契约作为唯一依据。
**Q4：文档会更新吗？**
接口有调整时官方会更新 YAML/JSON；建议定期重新拉取，保持本地契约与线上一致。
## 相关能力 / 下一步阅读
- [字典查询：通过 MCP 在 AI 客户端直接查字典](https://www.showapi.com/guides/dict-mcp-1524)
- [字典查询：5 分钟接入，从注册到查出第一个汉字详情](https://www.showapi.com/guides/dict-quickstart-1524)
- [字典查询：返回字段全解，ret_code 与 showapi_res_body 一文读懂](https://www.showapi.com/guides/dict-response-codes-1524)
- **本系列共 12 篇**：查看[字典查询指南总目录](https://www.showapi.com/guides/dict-guides-1524)
