导入 Postman / Swagger：用 OpenAPI 文档管理成语词典接口

# 导入 Postman / Swagger：用 OpenAPI 文档管理成语词典接口 > 接口：成语词典（apiCode=2964） · 集成能力：OpenAPI 3.0（YAML/JSON） · 是否免费：是 · 适用人群：注重 API 治理的团队、后端开发者 · 阅读时间：约 4 分钟 ## 核心要点 - 成语词典提供标准 OpenAPI 3.0 文档（YAML + JSON），覆盖全部三个接入点。 - 可导入 **Postman / Swagger UI** 等 API 工具，自动生成请求模板与 Mock，便于团队管理与调试。 - 文档即契约：把 YAML 纳入仓库，接口变更有迹可循。 > 说明：本文仅使用 Postman / Swagger UI 等通用 API 工具。按内容规范，全文不出现其他同类工具的名称。 ## Why：为什么要用 OpenAPI 管理 零散的 curl 片段不利于团队协作。把接口定义成 OpenAPI 文档，既能一键导入 API 工具生成可调试请求，也能作为前后端契约、纳入版本管理。成语词典已给出官方 YAML/JSON，省去你手写定义。 ## What：文档地址 | 格式 | 地址 | |------|------| | 在线查看 YAML | https://www.showapi.com/openapi/market/2964.yaml | | 下载 YAML | https://www.showapi.com/openapi/market/2964.yaml | | 查看 JSON | https://www.showapi.com/openapi/market/2964.json | 文档覆盖 2964-1 / 2964-2 / 2964-3 三个接入点，含参数与返回结构。 ## How：导入 API 工具 ### 方式 A：Postman 1. 打开 Postman → Import。 2. 选择「Link」粘贴 `https://www.showapi.com/openapi/market/2964.yaml`（或下载后选文件导入）。 3. 导入后自动生成三个请求（搜索/详情/随机），在 `appKey` 参数填入你的 AppKey 即可发送。 ### 方式 B：Swagger UI / Swagger Editor 1. 打开 Swagger UI 或 Swagger Editor。 2. 粘贴/上传上述 YAML。 3. 界面内可直接对每个接入点「Try it out」，填 `appKey` 与参数发起调用。 ## 进阶 / 边界 - **appKey 管理**：导入后把 `appKey` 设为环境变量，避免硬编码进集合、误提交。 - **Mock 数据**：API 工具可基于 schema 生成 Mock，用于前端联调；但真实释义仍以来自接口的数据为准。 - **版本治理**：把 YAML 存入仓库，接口有变时对比差异、更新文档，保持前后端一致。 - **契约测试**：可用该 OpenAPI 跑契约测试，确保实现与文档一致（如 `ret_code` 0 成功等约定）。 ## FAQ **Q：导入后为什么还要填 appKey？** appKey 是鉴权参数，需来自你的 ShowAPI 应用，不能预填在公开文档里。 **Q：YAML 和 JSON 选哪个导入？** 两者等价，按你用的工具习惯选；Postman/Swagger 都支持。 **Q：Mock 出来的释义能用吗？** Mock 仅按 schema 造结构，真实内容必须调接口获取。 **Q：文档覆盖全部接入点吗？** 覆盖，2964-1/2/3 均在 OpenAPI 文档中定义。 ## 相关能力 / 下一步阅读 - [通过 MCP 在 Cherry Studio / ChatBox 中直接用成语词典](https://www.showapi.com/guides/idiom-mcp-integration-2964) - [成语词典返回字段全解：showapi_res_body 与 ret_code 一文读懂](https://www.showapi.com/guides/idiom-dictionary-response-codes-2964) - [成语词典：5 分钟接入，从注册到第一条搜索结果](https://www.showapi.com/guides/idiom-dictionary-quickstart-2964) - **本系列共 15 篇**：查看[成语词典（apiCode=2964）官方指南总目录](https://www.showapi.com/guides/idiom-dictionary-guides-2964)