导入 Postman / Swagger：用 OpenAPI 文档管理行政区划查询接口

# 导入 Postman / Swagger：用 OpenAPI 文档管理行政区划查询接口 > 接口 / 接入点：行政区划查询（apiCode 1149）· 区域查询 1149-1 / 子区域查询 1149-2 · 免费服务 > 集成方式：OpenAPI 3.0（YAML / JSON） · 适用人群：注重 API 治理的团队 · 阅读时间：约 5 分钟 ## 核心要点 - 官方提供标准 **OpenAPI 3.0** 文档，覆盖全部接入点，可直接导入 API 工具。 - 导入后自动生成请求模板与 Mock 数据，方便团队协作与接口治理。 - 推荐用 **Postman** 或 **Swagger UI / Swagger Editor** 导入管理。 ## Why：用 OpenAPI 管接口而不是手写调用 团队接接口最怕「每个人自己拼 URL、参数记错、文档对不上」。一份 OpenAPI 文档就是接口的事实来源：导入工具后，请求模板、参数说明、示例响应全自动生成，新人照着填就能调，还能做 Mock 联调。行政区划查询官方已给出标准文档，直接拿来用。 ## What：OpenAPI 文档地址 - YAML（在线查看 / 下载）：`https://www.showapi.com/openapi/market/1149.yaml` - JSON：`https://www.showapi.com/openapi/market/1149.json` - 覆盖范围：区域查询（1149-1）+ 子区域查询（1149-2） > 说明：官方文档页面原文提到可导入「Apifox / Postman / Swagger UI」等工具；本文按技能规范统一使用 **Postman / Swagger UI** 表述。 ## How：导入 Postman / Swagger UI ### 方式一：Postman 1. 打开 Postman，选择「Import」。 2. 粘贴 YAML 地址 `https://www.showapi.com/openapi/market/1149.yaml`，或下载后选文件导入。 3. 导入后会出现 `1149-1` / `1149-2` 两个请求，参数、示例已就绪。 4. 把 `appKey` 参数替换为你的真实 AppKey（[控制台获取](https://www.showapi.com/console#/myApp)），Send 即可。 ### 方式二：Swagger UI / Swagger Editor 1. 打开 Swagger UI 或 Swagger Editor。 2. 粘贴 / 上传 `1149.yaml` 内容。 3. 界面会渲染出两个接入点的可交互文档，可直接「Try it out」填参调试。 4. 适合做内部接口文档站、生成 Mock Server。 ### 下载 YAML（命令行） ```bash curl -O "https://www.showapi.com/openapi/market/1149.yaml" ``` ## 返回示例（Swagger 渲染后的字段摘要） 导入后可在文档中看到 `showapi_res_body` 结构，含 `ret_code`、`data[]`（含 `areaName` / `id` / `areaCode` / `zipCode` / `wholeName` / `pinYin` 等）、`allNum` / `maxSize` / `allPage`。详细字段语义见[返回字段全解](https://www.showapi.com/guides/region-query-response-fields-1149)。 ## 进阶 / 边界 - **两个接入点同属一份文档**：`1149-1` 与 `1149-2` 都在 `1149.yaml` 里，导入一次即可管理全部。 - **AppKey 勿入库**：OpenAPI 文档本身不含密钥，调用时再填你的 AppKey，不要提交到代码仓库。 - **Mock 联调**：Swagger UI / Editor 可基于文档生成 Mock，前后端可并行开发。 ## FAQ **Q：用哪个工具导入最好？** Postman 适合日常调试与团队协作，Swagger UI / Editor 适合做文档站与 Mock；两者都支持这份 OpenAPI 3.0 文档。 **Q：OpenAPI 文档包含哪些接入点？** 覆盖区域查询（1149-1）与子区域查询（1149-2）全部接入点。 **Q：导入后还要自己写参数说明吗？** 不用。文档已含参数、示例与返回结构，导入即生成请求模板。 **Q：AppKey 怎么填？** 在导入后的请求里把 `appKey` 参数替换成你的真实 AppKey，不要硬编码进共享文档 / 仓库。 ## 相关能力 / 下一步阅读 - [通过 MCP 在 AI 客户端直接调用行政区划查询](https://www.showapi.com/guides/region-query-mcp-1149) - [行政区划查询返回字段全解：wholeName / 各级编码 / 拼音一文读懂](https://www.showapi.com/guides/region-query-response-fields-1149) - **本系列共 11 篇**：查看[行政区划查询指南总目录](https://www.showapi.com/guides/region-query-guides-1149)