全国城市空气质量查询：导入 Postman / Swagger 用 OpenAPI 文档管理接口

# 全国城市空气质量查询：导入 Postman / Swagger 用 OpenAPI 文档管理接口 > 接口/接入点：全国城市空气质量查询（apiCode=104）· 接口级 OpenAPI 3.0 · 免费 · 适用人群：API 治理 / 后端团队 · 阅读时间：约 6 分钟 ## 核心要点 - 官方提供标准 OpenAPI 3.0 文档（YAML / JSON），覆盖 104-41 排行榜与 104-42 单城查询全部接入点。 - 可导入 **Postman / Swagger UI / Swagger Editor** 自动生成请求模板与 Mock 数据，便于团队管理与联调。 - 也可直接供 AI Agent 消费；文档地址稳定，适合纳入接口资产库统一治理。 ## Why：为什么用 OpenAPI 管理 当团队接入多个接口时，散落的 curl 片段容易过期、难协作。一份 OpenAPI 文档是接口的「单一事实源」：设计、联调、Mock、代码生成都基于它。本篇教你把 104 接口的官方 OpenAPI 文档接入主流工具链。 ## What：文档地址 | 项 | 地址 | |----|------| | OpenAPI YAML | `https://www.showapi.com/openapi/market/104.yaml` | | OpenAPI JSON | `https://www.showapi.com/openapi/market/104.json` | | 覆盖范围 | 接口级，含 104-41 与 104-42 全部接入点 | ## How：导入到工具 ### 导入 Postman 1. 打开 Postman → 左侧 `Import`。 2. 粘贴 YAML 地址 `https://www.showapi.com/openapi/market/104.yaml`（或先下载再选文件）。 3. 导入后自动生成两个请求集合（排行榜 / 单城查询），在 `appKey` 与 `area` 处填入你的参数即可发送。 ### 用 Swagger UI / Swagger Editor 预览与 Mock - **Swagger Editor**：打开 https://editor.swagger.io ，`File → Import URL` 粘贴上述 YAML，即可在线校验、预览并生成 Mock Server。 - **Swagger UI**：将 YAML 托管到你的文档站，用 Swagger UI 渲染出可交互的接口页，方便前后端联调。 ### 直连对照（cURL，便于核对文档） ```bash # 单城查询 104-42 curl -X POST "https://route.showapi.com/104-42?appKey=YOUR_APPKEY" \ -H "content-type: application/x-www-form-urlencoded" -d "area=%E5%8C%97%E4%BA%AC" # 排行榜 104-41 curl -X POST "https://route.showapi.com/104-41?appKey=YOUR_APPKEY" \ -H "content-type: application/x-www-form-urlencoded" ``` ## 返回示例与解析 导入后，单城查询的请求体为 `area`（城市名），响应结构即 `showapi_res_body`（含 `aqi`/`pm2_5`/`quality` 等）。可在 Postman 的 `Tests` 脚本里断言 `pm2_5` 为数值、`quality` 属于 6 类之一，做基础契约校验。 ## 进阶 / 边界 - **密钥管理**：Postman 环境变量的 `appKey` 不要提交到团队仓库；用环境变量/密钥引用代替明文。 - **文档与线上一致性**：以官方 OpenAPI 文档为准；若发现字段（如 `o3_8h:"_"` 占位、`primary_pollutant` 空值）与文档示例有出入，以线上实际返回为准。 - **Mock 数据仅用于联调**：Mock 返回非真实监测值，上线前务必用真实 AppKey 跑通。 - **不含地理坐标**：接口返回 `area_code`（拼音）但无经纬度，地图类需求需另接地理编码。 ## FAQ **Q1：OpenAPI 文档覆盖哪些接入点？** 接口级文档覆盖 104-41 排行榜与 104-42 单城查询全部接入点。 **Q2：导入后怎么快速发请求？** 在 Postman 生成的集合里填 `appKey`（URL 参数）与 `area`（表单）即可发送；Swagger UI 也可在页面直接试。 **Q3：能干嘛除了联调？** 可用于契约测试、代码生成（如 openapi-generator）、Mock Server、纳入 API 资产库统一治理。 **Q4：文档和实测字段不一致以谁为准？** 以线上实际返回为准；如确有偏差可向官方反馈，文档更新前按「字段全解」篇处理边界值。 ## 相关能力 / 下一步阅读 - [全国城市空气质量查询：通过 MCP 在 AI 客户端中直接查询](https://www.showapi.com/guides/air-quality-mcp-104) - [全国城市空气质量查询：5 分钟接入，拿到第一条空气质量数据](https://www.showapi.com/guides/air-quality-quickstart-104) - **本系列共 11 篇**：查看[全国城市空气质量查询 · 指南总目录](https://www.showapi.com/guides/air-quality-guides-104)