导入 Postman / Swagger UI：用 OpenAPI 文档管理歇后语查询接口

# 导入 Postman / Swagger UI：用 OpenAPI 文档管理歇后语查询接口 - **接口/接入点**：歇后语查询 · 1635-1（OpenAPI 覆盖全部接入点） - **是否免费**：是 - **请求方式**：POST / GET - **返回格式**：JSON - **适用人群**：注重 API 治理的团队、后端工程师 - **阅读时间**：约 6 分钟 ## 核心要点 - 官方提供标准 OpenAPI 3.0 文档（YAML/JSON），可导入 **Postman / Swagger UI** 做请求模板与 Mock 管理。 - 文档地址：`https://www.showapi.com/openapi/market/1635.yaml`（YAML）与 `.json`。 ## Why：为什么要导入 OpenAPI 团队接手一个接口，最怕"参数全靠口口相传"。把官方 OpenAPI 文档导入 Postman / Swagger UI，能自动生成请求模板、可见字段结构、可 Mock，新人上手快、文档不漂移。 ## What：文档资源 | 资源 | 地址 | |------|------| | OpenAPI YAML | https://www.showapi.com/openapi/market/1635.yaml | | OpenAPI JSON | https://www.showapi.com/openapi/market/1635.json | | 接口详情 | https://www.showapi.com/apiGateway/view/1635 | ## How：导入到工具 ### 导入 Postman 1. 打开 Postman → Import； 2. 选择「Link」粘贴 `https://www.showapi.com/openapi/market/1635.yaml`； 3. 导入后自动生成请求集合，填入 AppKey 即可发起调用； 4. 用集合里的示例请求做联调，无需手敲参数。 ### 导入 Swagger UI 1. 本地启动 Swagger UI（或用支持 URL 的实例）； 2. 填入 YAML 地址 `https://www.showapi.com/openapi/market/1635.yaml`； 3. 在页面里直接 `Try it out`，填 `num` 与 AppKey 发起测试。 ### 用 OpenAPI 校验你的代码（Python 示例） ```python import requests, yaml # 拉取官方文档做字段对照 spec = yaml.safe_load(requests.get( "https://www.showapi.com/openapi/market/1635.yaml", timeout=15).text) # 确认请求参数确有 num，无 category/page（避免误用） params = spec["paths"]["/1635-1"]["post"].get("requestBody", {}).get("content",{}).get("application/x-www-form-urlencoded",{}).get("schema",{}).get("properties",{}) print("请求参数:", list(params.keys())) # 预期仅 ['num'] ``` ## 返回示例与解析 OpenAPI 中业务体字段：`ret_code`(string)、`remark`(string)、`contentlist`(string，实际为数组)、`maxResult`/`allNum`/`allPages`/`currentPage`(string)。以真实返回为准，`contentlist` 按数组遍历。 ## 进阶 / 边界 - **contentlist 类型标注**：YAML 标为 string，真实返回是数组，按数组解析（文档小瑕疵）。 - **无分类参数**：文档 `parameters` 仅 `num`，不要据描述臆造 category。 ## FAQ **Q：YAML 和 JSON 用哪个？** A：二者内容一致，Postman/Swagger UI 都支持；按需选，YAML 更可读。 **Q：导入后能直接调吗？** A：能，填入 AppKey 即可发起请求并看返回。 **Q：contentlist 在文档里是 string？** A：YAML 类型标注为 string，但真实返回是数组，按数组解析即可。 **Q：导入后能用它做 Mock 吗？** A：可以，Postman / Swagger UI 都支持基于 OpenAPI 生成 Mock 请求与示例响应。 ## 相关能力 / 下一步阅读 - [通过 MCP 在 Cherry Studio / ChatBox 中直接调用歇后语查询](https://www.showapi.com/guides/xiehouyu-mcp-integration-1635) - [歇后语查询返回字段全解：contentlist / ret_code / 分页字段一文读懂](https://www.showapi.com/guides/xiehouyu-response-fields-1635) - **本系列共 13 篇**：查看[歇后语查询指南总目录](https://www.showapi.com/guides/xiehouyu-guides-1635)