天气预报国际版：导入 Postman / Swagger UI，用 OpenAPI 文档管理接口

# 天气预报国际版：导入 Postman / Swagger UI，用 OpenAPI 文档管理接口 > 接口：天气预报国际版（apiCode=3540）· 免费接口 · OpenAPI 3.0 · 适用人群：团队协作开发者、API 治理负责人 · 阅读时间：约 6 分钟 ## 核心要点 - 天气预报国际版提供官方 **OpenAPI 3.0** 文档，覆盖全部 3 个接入点：[YAML](https://www.showapi.com/openapi/market/3540.yaml) / [JSON](https://www.showapi.com/openapi/market/3540.json)。 - 本文写作时已实测：JSON 文档可直接访问，内容为 `openapi: 3.0.3`、标题"天气预报国际版"的规范描述。 - 把 YAML/JSON 导入 **Postman** 或用 **Swagger UI** 渲染后，三个接入点变成可点击调试的集合，团队不必再对着网页手动抄参数。 ## Why 接口文档散落在网页上，是团队协作里最常见的低效来源：前端要问后端"这个字段什么类型"，测试要手动拼 URL，新人入职先把参数表抄一遍。 OpenAPI 规范解决了这件事：接口被描述成一份机器可读的契约文件，Postman / Swagger UI 这类工具都能消费它——自动生成请求模板、在线调试、Mock 数据、变更对比。天气预报国际版官方直接提供这份契约（OpenAPI 3.0），本文讲怎么把它变成你团队的接口资产。 ## What | 项目 | 说明 | |------|------| | OpenAPI 版本 | 3.0.3（实测 JSON 返回内容确认） | | YAML | https://www.showapi.com/openapi/market/3540.yaml | | JSON | https://www.showapi.com/openapi/market/3540.json | | 覆盖范围 | 全部接入点：3540-1 当前天气 / 3540-2 24小时预报 / 3540-3 14天预报 | | 推荐工具 | **Postman**（导入集合、团队协作）、**Swagger UI / Swagger Editor**（在线渲染调试） | 实测 JSON 文档头部： ```json { "openapi": "3.0.3", "info": { "title": "天气预报国际版", "description": "通过与多个全球天气服务商及高分辨率本地天气模型合作，……", "version": "1.0.0" } } ``` ## How ### 1. 下载文档 ```bash # 下载 OpenAPI 文档（JSON 已实测可直接获取） curl -o weather-3540.json https://www.showapi.com/openapi/market/3540.json ``` 浏览器直接打开 [YAML](https://www.showapi.com/openapi/market/3540.yaml) 或 [JSON](https://www.showapi.com/openapi/market/3540.json) 链接另存亦可。 ### 2. 导入 Postman 1. 打开 Postman → **Import**； 2. 选择刚下载的 `weather-3540.json`（或粘贴 URL 导入）； 3. 导入完成后，左侧出现"天气预报国际版"集合，三个接入点各成一条请求； 4. 在集合的 Variables（或每个请求的参数里）把 `appKey` 配置为你的 AppKey（[获取入口](https://www.showapi.com/console#/myApp)），即可在 Postman 内直接 Send 调试。 ### 3. 用 Swagger UI 渲染调试 把文档喂给 Swagger UI（自部署或 Swagger Editor 在线版），即可获得可交互的接口页面：展开任一接入点 → 填入参数与 AppKey → **Execute** 在线执行并查看响应。 ### 4. 导入后怎么用起来 - **请求模板即文档**：三个接入点的参数（`name` / `lon` / `lat`）在导入后自动成表，新人不再抄参数； - **环境变量管理密钥**：AppKey 放 Postman Environment，多环境（测试/生产）切换不硬编码； - **Mock 联调**：前端在接口未接通前可用 Postman Mock Server 按该契约出假数据（天气字段结构见[返回字段全解](https://www.showapi.com/guides/global-weather-response-fields-3540)）； - **变更守护**：文档更新时重新导入对比，接口变更第一时间可见。 ## 返回示例与解析 Postman 中 Send 一次（3540-1，name=London）得到的真实响应结构： ```json { "showapi_res_code": 0, "showapi_fee_num": 1, "showapi_res_body": { "ret_code": 0, "remark": "查询成功", "cityInfo": { "city": "伦敦", "city_en": "London", "time_zone": "Europe/London" }, "now": { "temperature": 18.9, "weather": "阴天", "feels_like": 17.6 } } } ``` 在 Postman 的 Tests 里可以加断言把契约固化下来： ```js pm.test("调用成功", () => { const d = pm.response.json(); pm.expect(d.showapi_res_code).to.eql(0); pm.expect(d.showapi_res_body.ret_code).to.eql(0); }); ``` ## 进阶与边界 - **YAML/JSON 可达性说明**：本文实测 JSON 链接可直接返回规范内容；YAML 链接在命令行 HEAD 请求时返回 403（站点防护策略所致），浏览器访问与下载以官网页面入口为准。两份文件内容等价，任选其一导入。 - **导入的是契约，不是鉴权配置**：OpenAPI 文档描述参数与结构；`appKey` 这类鉴权参数导入后仍需在工具里手动配置。 - **文档与实测的差异**：OpenAPI 文档描述的参数与实际返回以实测为准（如城市字段实际返回 `city`/`city_en`，文档表曾写作 `area`），遇到对不上的字段先看[返回字段全解](https://www.showapi.com/guides/global-weather-response-fields-3540)的实测修正。 - **配合 MCP**：除了导入工具，还可以用 MCP 把接口直接接入 AI 客户端，见[MCP 集成](https://www.showapi.com/guides/global-weather-mcp-integration-3540)。 ## FAQ **Q1：Postman 导入后请求能直接发吗？** 能，但需要先配置 AppKey。把 URL 中或参数里的 `{your_appKey}` 替换为真实 AppKey（建议放 Environment 变量）。 **Q2：OpenAPI 文档会随接口更新吗？** 文档版本号实测为 `1.0.0`；接口能力变化时以官网最新文档为准，建议定期重新导入对比。 **Q3：可以用 OpenAPI 文档生成客户端 SDK 吗？** 可以。文档符合 OpenAPI 3.0.3 规范，可用 openapi-generator 等工具生成各语言客户端代码，再配合 `appKey` 调用。 **Q4：导入 Postman 后怎么批量测多城市？** 用 Collection Runner：把多个城市的请求放进同一集合（或用 CSV 数据文件驱动 `name` 变量）批量执行；注意控制速率，见[多城市批量管理](https://www.showapi.com/guides/global-weather-multicity-3540)。 **Q5：Swagger UI 显示的参数类型和实际返回不一致怎么办？** 以实际返回为准并把问题反馈给官方。已知案例：城市字段文档表与实测存在出入（`area` vs `city`/`city_en`），详见[返回字段全解](https://www.showapi.com/guides/global-weather-response-fields-3540)。 ## 下一步阅读 - [天气预报国际版：通过 MCP 在 AI 客户端中直接查天气](https://www.showapi.com/guides/global-weather-mcp-integration-3540) - [天气预报国际版：5 分钟快速开始（注册到第一次全球天气查询）](https://www.showapi.com/guides/global-weather-quickstart-3540) - [天气预报国际版指南总目录](https://www.showapi.com/guides/global-weather-guides-3540) - **本系列共 12 篇**：查看[天气预报国际版指南总目录](https://www.showapi.com/guides/global-weather-guides-3540)