手机归属地查询 OpenAPI 文档：用 Postman 与 Swagger UI 管理接口
约 12 分钟 进阶手机号码归属地查询OpenAPI 3.0PostmanSwagger UI
# 手机归属地查询 OpenAPI 文档：用 Postman 与 Swagger UI 管理接口
接口：手机归属地查询（apiCode=6，接入点 6-1）｜是否免费：是，注册后默认可调用，设使用档次限制｜请求方式：POST / GET｜返回格式：JSON｜适用人群：API 治理、测试与联调负责人｜阅读时间：约 8 分钟｜最后实测核对：2026-09-18
官方为手机归属地查询接口提供 OpenAPI 3.0 文档，YAML 和 JSON 两种格式。把它导入 Postman 或丢进 Swagger UI，接口的参数、响应结构、超时值就变成一份可执行、可 Mock 的描述。这篇讲文档里有哪些字段、怎么导入，以及文档声明与实际返回的差异该按哪个口径处理。
## 核心要点
- 文档地址有两个：`https://www.showapi.com/openapi/market/6.yaml` 和 `https://www.showapi.com/openapi/market/6.json`，内容等价。
- 超时值只在 OpenAPI 里能看到，接口详情页不展示：`x-read-timeout: 10`、`x-connect-timeout: 10`。
- 文档声明的响应字段是 9 个，实测返回里有 11 个，缺的 `postCode` 和 `remark` 要按可选字段处理。
## 文档里有什么
2026-09-18 实测请求这两份文档，关键信息如下。
| 项目 | 内容 |
|------|------|
| OpenAPI 版本 | 3.0.3 |
| 接口标题 | 手机号码归属地查询 |
| 路径 | `/6-1`，全接口只有这一个接入点 |
| `x-pointCode` | 1 |
| `x-mode` | mapping |
| `x-read-timeout` | 10 |
| `x-connect-timeout` | 10 |
| 鉴权 | `AppKeyAuth`，apiKey 类型，位于 query 参数 `appKey` |
| 服务地址 | `https://route.showapi.com` |
| 必填参数 | `num`（query，String，必填） |
文档声明的响应字段在 `showapi_res_body` 下有 9 个：`prov`、`city`、`name`、`num`、`provCode`、`type`、`cityCode`、`ret_code`、`areaCode`。实测返回里还有 `postCode` 和 `remark`，这两个字段文档未登记。
用一行命令核对文档里的路径数和字段数：
```bash
curl -s "https://www.showapi.com/openapi/market/6.json" --max-time 10 | python -c "
import sys, json
doc = json.load(sys.stdin)
print('paths:', list(doc['paths'].keys()))
props = doc['paths']['/6-1']['post']['responses']['200']['content']['application/json']['schema']
print('响应 schema 层级:', list(props.keys()))
timeouts = {k: (v.get('x-read-timeout'), v.get('x-connect-timeout')) for k, v in doc['paths'].items()}
print('超时(read/connect):', timeouts)
"
```
## 导入 Postman
第一步，把文档下载到本地。
```bash
curl -s -o phone-attribution-6.yaml "https://www.showapi.com/openapi/market/6.yaml" --max-time 15
```
第二步，打开 Postman，在左上角选 Import，把文件拖进导入窗口。Postman 识别 OpenAPI 3.0 后会生成一个集合，里面包含 `/6-1` 这个请求，参数 `num` 已经按 schema 生成好输入位。
第三步，在集合上配置环境变量，把 AppKey 从请求里抽出来。
```
环境变量：showapi_appkey = 你的 AppKey
请求 URL：{{base_url}}/6-1?appKey={{showapi_appkey}}&num={{phone}}
集合变量：base_url = https://route.showapi.com
```
这样 AppKey 只存在环境变量里，导出的集合文件不会带上密钥，适合放进代码仓库做接口资产的版本管理。
第四步，给请求加一个示例响应。把实测拿到的真实返回存进 Postman 的 Example，之后的响应结构校验会以它为基准。
```json
{
"showapi_res_error": "",
"showapi_res_id": "6aaca381fb638c2f6956a193",
"showapi_res_code": 0,
"showapi_fee_num": 1,
"showapi_res_body": {
"provCode": "110000", "areaCode": "010", "ret_code": 0, "remark": "",
"postCode": "100000", "num": 1380013, "cityCode": "110100",
"name": "移动全球通卡", "type": 1, "city": "北京", "prov": "北京"
}
}
```
## 用 Swagger UI 和 Swagger Editor 查看
Swagger Editor 可以直接打开 YAML 源文件，右侧实时渲染出接口文档，改一处参数说明立刻能看到效果，适合做文档评审。
Swagger UI 适合部署在团队内部做一个只看不写的接口说明页。把 YAML 文件放在静态目录下，用 Docker 起一个容器指向它：
```bash
docker run -p 8080:8080 \
-e SWAGGER_JSON=/spec/phone-attribution-6.yaml \
-v "$(pwd)/phone-attribution-6.yaml:/spec/phone-attribution-6.yaml" \
swaggerapi/swagger-ui
```
打开 `http://localhost:8080` 就能看到渲染后的接口文档，Try it out 按钮可以填 AppKey 直接发请求。
## Mock 与 SDK 生成
Postman 的 Mock Server 基于集合里的 Example 返回响应，前端在后端接口还没联调时，就可以用 Mock 地址先把页面渲染逻辑写完。把上面那段真实返回存成 Example，Mock 返回的结构就是真实结构。
SDK 生成走 OpenAPI 的标准链路。用 Swagger Codegen 或同类工具，指定 `-l python` 之类的语言参数，从 YAML 生成客户端代码，省掉手写请求封装的步骤。
## 文档与实测的差异怎么处理
三处差异值得在处理接口资产时确认。
| 项目 | 文档口径 | 实测口径（2026-09-18） |
|------|----------|------------------------|
| 响应字段个数 | 9 个，无 `postCode`、`remark` | 11 个，含 `postCode`、`remark` |
| `provCode` 类型 | Number | String，返回 `"110000"` |
| `cityCode` 类型 | String | String，返回 `"110100"` |
字段类型的差异会直接影响生成的 SDK。如果按文档把 `provCode` 生成为数字类型，反序列化时会遇到类型不匹配。做接口资产时按实测口径改一遍文档再生成代码，比生成后逐个改要省事。
差异的完整清单和取值说明在[返回字段全解](https://www.showapi.com/guides/phone-attribution-response-fields-6)。
## 免费接口的档位信息放在哪
OpenAPI 文档描述的是接口契约，不含计费与档位信息。手机归属地查询是免费接口，档位、每日调用量、并发上限这些内容在[免费接口与档位说明](https://www.showapi.com/free-api)页面，治理文档里需要这部分内容时单独引用这个地址。
## FAQ
**Q1：YAML 和 JSON 两份文档有区别吗？**
内容等价，只是序列化格式不同。YAML 适合人工阅读和放进代码仓库，JSON 适合程序直接解析。
**Q2：文档里有几个接入点？**
只有一个，路径是 `/6-1`。文档的 `paths` 字段可以直接核对，别只看接口页侧栏。
**Q3：超时值在哪里看？**
在 OpenAPI 文档里，字段是 `x-read-timeout` 和 `x-connect-timeout`，实测都是 10。接口详情页不展示这两个值。
**Q4：导入 Postman 后 AppKey 怎么写？**
放进 Postman 环境变量，请求里用 `{{showapi_appkey}}` 引用。这样导出的集合文件不含密钥，可以直接进代码仓库。
**Q5：文档声明的字段和实际返回不一致怎么办？**
以实际返回为准，同时把差异记在自己的接口资产里。字段增删或类型变化的差异会影响生成的 SDK，生成代码前先对齐一遍。
**Q6：能用文档生成 SDK 吗？**
可以。OpenAPI 3.0 的标准工具链都支持，生成前先把 `provCode` 这类类型差异改到位。
## 下一步阅读
- [手机归属地查询返回字段全解：11 个字段的类型、取值与粒度](https://www.showapi.com/guides/phone-attribution-response-fields-6) —— 文档与实测的差异清单
- [手机归属地查询 MCP 服务：在 AI 客户端里直接问号码归属地](https://www.showapi.com/guides/phone-attribution-mcp-6) —— 另一条集成通道
- [手机归属地查询接口怎么用？从 AppKey 到第一条真实返回的完整路径](https://www.showapi.com/guides/phone-attribution-quickstart-6) —— 不依赖工具链的最小调用
- **本系列共 12 篇**：查看[手机归属地查询指南总目录](https://www.showapi.com/guides/phone-attribution-guides-6)
