星座运势 API 导入 Postman / Swagger UI：OpenAPI 3.0 文档的用法
约 13 分钟 进阶星座运势APIOpenAPIPostmanSwaggerUI
# 星座运势 API 导入 Postman / Swagger UI：OpenAPI 3.0 文档的用法
接口 872（两接入点）· 免费服务 · 适用：注重接口治理与团队协作的开发者 · 阅读时间：约 6 分钟 · 最后实测核对：2026-09-18
## 核心要点
- 星座运势接口（apiCode=872）提供标准 OpenAPI 3.0.3 文档，同时覆盖接入点 1 与接入点 2。
- 文档地址有两份：`https://www.showapi.com/openapi/market/872.yaml` 与 `https://www.showapi.com/openapi/market/872.json`。
- 接入点级扩展字段里带超时配置，2026-09-18 读取到的值是接入点 1 为 15 秒 / 15 秒，接入点 2 为 5 秒 / 5 秒，接口详情页不展示这两个值。
## 文档资源
| 资源 | 链接 |
|---|---|
| OpenAPI 3.0（YAML） | `https://www.showapi.com/openapi/market/872.yaml` |
| OpenAPI 3.0（JSON） | `https://www.showapi.com/openapi/market/872.json` |
| 接口详情页 | `https://www.showapi.com/apiGateway/view/872` |
文档头部的实测值：`openapi` 为 `3.0.3`，`info.title` 为「星座运势」，`info.version` 为 `1.0.0`，`servers` 指向 `https://route.showapi.com`。
## 接入点与扩展字段
`paths` 下有两个路径，与接口的接入点一一对应：
| 路径 | 接入点 | `x-pointCode` | `x-mode` | `x-read-timeout` / `x-connect-timeout` |
|---|---|---|---|---|
| `/872-1` | 星座运势查询 | `1` | `mapping` | `15` / `15` |
| `/872-2` | 星座配对 | `2` | `mapping` | `5` / `5` |
`x-read-timeout` 与 `x-connect-timeout` 是接口文档页看不到的两个值，写客户端超时配置时按这两个数设置。接入点 2 的超时比接入点 1 短，两个请求不要共用一个 15 秒的超时。
两个路径都只声明了 `post`，请求体用 `application/x-www-form-urlencoded`。`appKey` 以 `in: query` 的形式定义在文档参数里。
## 导入 Postman
1. 打开 Postman，选择 Import。
2. 选 Link 方式，粘贴 `https://www.showapi.com/openapi/market/872.yaml`。
3. 导入后会生成一个 Collection，里面是 `872-1` 与 `872-2` 两个请求。
4. 在请求的 `appKey` 参数里填入你的 AppKey，或者建一个环境变量 `appKey` 并在请求中引用。
两个请求的默认参数集来自文档，`star`、`date`、`needX` 这类可选参数可以直接在 Params 面板里勾选启用。
## 导入 Swagger UI / Swagger Editor
把 YAML 内容贴进 Swagger Editor，右侧会渲染出可交互的接口列表，点开任一接入点就能填参数并发送请求。适合给团队做接口速查，不需要装客户端。
## 用文档生成代码前的准备
OpenAPI 文档可以喂给 openapi-generator 之类的工具生成客户端骨架，生成后需要补三件事：
- 把 `appKey` 从 query 参数改为环境变量注入，不要硬编码在生成的客户端里。
- 超时按接入点分别设置，接入点 2 用 5 秒。
- 业务层的 `ret_code` 判断要自己加。文档描述的 `ret_code` 标注为 String，2026-09-18 实测返回的是数字 `0`，生成代码里统一按字符串化比较。
Python 里用 requests 直接按文档结构调用：
```python
import requests
def call(path: str, params: dict, timeout: int) -> dict:
"""path 取 872-1 / 872-2，timeout 按 OpenAPI 的 x-read-timeout 传入。"""
data = requests.post(
f"https://route.showapi.com/{path}",
data={**params, "appKey": "YOUR_APPKEY"}, # 文档定义 appKey 在 query，表单同样生效
timeout=timeout,
).json()
if data.get("showapi_res_code") != 0:
raise RuntimeError(f"系统错误: {data.get('showapi_res_error')}")
body = data["showapi_res_body"]
if str(body.get("ret_code")) != "0":
raise RuntimeError(f"业务错误: {body.get('remark')}")
return body
# 接入点 1，超时按 x-read-timeout = 15
print(call("872-1", {"star": "shizi", "needWeek": "1"}, 15)["day"]["summary_star"])
# 接入点 2，超时按 x-read-timeout = 5
print(call("872-2", {"star1": "tianxie", "gender1": "1",
"star2": "shuiping", "gender2": "0"}, 5)["match"])
```
cURL（GET 形式同样可用）：
```bash
# 接入点 1：15 秒
curl -G "https://route.showapi.com/872-1" \
--data-urlencode "appKey=YOUR_APPKEY" \
--data-urlencode "star=shizi" \
--max-time 15
# 接入点 2：5 秒
curl -G "https://route.showapi.com/872-2" \
--data-urlencode "appKey=YOUR_APPKEY" \
--data-urlencode "star1=tianxie" \
--data-urlencode "gender1=1" \
--data-urlencode "star2=shuiping" \
--data-urlencode "gender2=0" \
--max-time 5
```
Node.js（fetch）：
```javascript
async function call(path, params, timeoutMs) {
const url = new URL(`https://route.showapi.com/${path}`);
url.searchParams.set("appKey", "YOUR_APPKEY");
Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
const data = await res.json();
if (String(data.showapi_res_body?.ret_code) !== "0") throw new Error("业务失败");
return data.showapi_res_body;
}
console.log(await call("872-1", { star: "shizi" }, 15000));
console.log(await call("872-2",
{ star1: "tianxie", gender1: "1", star2: "shuiping", gender2: "0" }, 5000));
```
## 文档与实测的差异
读文档时有三处需要按实测理解，2026-09-18 核对如下：
| 项 | 文档口径 | 实测 |
|---|---|---|
| `day` / `tomorrow` / `week` / `month` / `year` | `Object[]` | 单个对象 |
| `ret_code` | 参数表标注 String | 数字 `0` |
| `month` 的字段表 | 未列 `lucky_num`、`lucky_color`、`day_notice` | 三个字段都有返回 |
这几个差异不影响导入流程，写解析代码时按实测处理即可。字段逐个说明见返回字段全解那篇。
## 与 MCP 的取舍
需要 AI 客户端在对话里直接调用，用 MCP 服务；需要接口测试、Mock、代码生成、团队协作，用 OpenAPI 文档。两者不冲突，可以同时配。
## FAQ
**Q1：导入后只有两个请求，接入点是不是少列了？**
没有少。接口 872 共 2 个接入点，对应文档里的 `/872-1` 与 `/872-2`，与接口详情页侧栏一致。
**Q2：超时该设多少？**
按文档的接入点级扩展字段设置。2026-09-18 读取到接入点 1 为读 15 秒 / 连接 15 秒，接入点 2 为读 5 秒 / 连接 5 秒。
**Q3：OpenAPI 里为什么只有 `post`？**
文档只声明了 `post`，请求体为 `application/x-www-form-urlencoded`。接口详情页标注请求方式为 POST / GET，GET 形式在调用时同样可用。
**Q4：能生成多语言 SDK 吗？**
可以。把 YAML 交给 openapi-generator 一类的工具即可，生成后记得按上面三件事做调整：密钥走环境变量、超时按接入点分开、业务层 `ret_code` 自己判。
**Q5：文档和实测不一致时按哪个写代码？**
按实测写。三处已知差异已在上面列出，解析代码统一按实测的形态处理。
**Q6：`appKey` 在文档里是 query 参数吗？**
是。`in: query`，实际调用时放在 URL 查询串或表单参数里都可以。
## 下一步阅读
- [星座运势 API 接进 Cherry Studio / ChatBox：MCP 配置](https://www.showapi.com/guides/horoscope-mcp-872)
- [星座运势查询：用 Python / cURL / Node.js 跑通第一次调用](https://www.showapi.com/guides/horoscope-quickstart-872)
- [星座配对：用四个必填参数算出配对指数](https://www.showapi.com/guides/constellation-match-quickstart-872)
- [星座运势查询返回字段全解：五个周期的字段对照](https://www.showapi.com/guides/horoscope-response-fields-872)
- **本系列共 13 篇**：查看[星座运势 API 指南总目录](https://www.showapi.com/guides/horoscope-guides-872)
