导入 Postman / Swagger：用 OpenAPI 文档管理测吉凶接口
# 导入 Postman / Swagger：用 OpenAPI 文档管理测吉凶接口
> 接口/接入点：测吉凶 apiCode=1617（OpenAPI 覆盖全部 4 个接入点） · 免费服务 · 适用人群：注重 API 治理的团队 · 阅读时间：约 5 分钟
## 核心要点
- 测吉凶提供标准 OpenAPI 3.0 文档（YAML/JSON），可一键导入 **Postman / Swagger UI / Swagger Editor** 管理。
- 导入后自动生成四个接入点的请求模板与参数说明，团队无需手查文档即可联调。
- 本文**不使用 Apifox**（按内容规范统一以 Postman / Swagger 表述）。
## Why：用 OpenAPI 做 API 治理
接口多了以后，靠口口相传参数容易出错。OpenAPI 是行业标准的接口描述文件，导入 API 工具后能生成可执行的请求模板、Mock 与文档，团队协作效率直接拉满。
## What：OpenAPI 文档地址
| 格式 | 地址 |
|------|------|
| YAML（在线/下载） | `https://www.showapi.com/openapi/market/1617.yaml` |
| JSON | `https://www.showapi.com/openapi/market/1617.json` |
文档覆盖 1617-1~1617-4 全部接入点，含路径、参数、响应结构。
## How：导入到 API 工具
### 方式一：Swagger UI / Swagger Editor
1. 打开 Swagger Editor（或任意 Swagger UI 实例）。
2. 选择「File → Import URL」，填入 `https://www.showapi.com/openapi/market/1617.yaml`。
3. 导入后左侧列出四个 `POST /1617-N` 路径，点开即可「Try it out」填参调试。
### 方式二：Postman
1. 打开 Postman → Import。
2. 选择「Link」粘贴 `https://www.showapi.com/openapi/market/1617.yaml`（或下载后选文件导入）。
3. Postman 自动生成四个请求集合，每个含 `mobile`/`carNo`/`qq`/`companyName` 参数与示例。
### 方式三：命令行拉取（团队归档）
```bash
curl -O "https://www.showapi.com/openapi/market/1617.yaml"
# 用 yq / openapi-cli 做校验或生成 Mock
```
## 返回示例与解析
OpenAPI 中每个接入点的 `requestBody` 明确标注必填参数，例如 1617-1：
```yaml
/1617-1:
post:
summary: 手机号测吉凶
requestBody:
content:
application/x-www-form-urlencoded:
schema:
properties:
mobile:
type: string
description: 手机号码
required: [mobile]
```
这与[返回字段全解](https://www.showapi.com/guides/fortune-response-fields-1617)一致。注意：文档把 `expList` 标为 `type: string`，但**实测为字符串数组**，以实测为准。
## 进阶 / 边界
- **expList 类型以实测为准**：OpenAPI 标注 `string`，实测返回数组，团队解析代码按数组处理。
- **鉴权参数 `appKey`**：OpenAPI 中定义为 query 级 `apiKey`（AppKeyAuth），导入工具后记得在请求里填你的 AppKey。
- **Mock 数据**：Swagger UI 的 Try-it-out 会真实发请求（消耗免费额度）；纯 Mock 请用 openapi-cli 本地生成，不实际调用。
- 想看四个接入点逐一用法，见各[专篇](https://www.showapi.com/guides/fortune-guides-1617)。
## FAQ
**Q：OpenAPI 文档里 expList 标成 string，我该信哪个？**
信实测。文档生成时类型标注有误，真实返回是字符串数组；解析与展示都按数组处理。
**Q：能用 Swagger UI 直接调试吗？**
能。Try-it-out 填参即发真实请求（消耗免费额度），适合联调；纯预览用 Swagger Editor 即可。
**Q：Postman 导入后怎么填 AppKey？**
在生成的请求 URL 或 Params 里填 `appKey=YOUR_APPKEY`（query 参数），与文档 AppKeyAuth 定义一致。
**Q：四个接入点在一个文档里吗？**
是。一份 1617.yaml 含 /1617-1~4 全部路径，导入后四个请求模板齐全。
## 相关能力 / 下一步阅读
- [通过 MCP 在 AI 客户端直接调用测吉凶（Cherry Studio / ChatBox）](https://www.showapi.com/guides/fortune-mcp-guide-1617)
- [测吉凶返回字段全解：ret_code、remark 与 expList 数组一文读懂](https://www.showapi.com/guides/fortune-response-fields-1617)
- [测吉凶：5 分钟接入指南（手机号/车牌号/QQ号/公司名）](https://www.showapi.com/guides/fortune-quickstart-1617)
- **本系列共 13 篇**：查看[测吉凶指南总目录](https://www.showapi.com/guides/fortune-guides-1617)
