生肖运势查询：导入 Postman / Swagger UI 管理接口（OpenAPI 3.0）

# 生肖运势查询：导入 Postman / Swagger UI 管理接口（OpenAPI 3.0） > 元信息：生肖运势查询（接入点 1） · 免费 · OpenAPI 3.0 · JSON · API 治理团队、中高级开发者 · 阅读约 6 分钟 ## 核心要点 - 易源提供标准 **OpenAPI 3.0** 文档（YAML / JSON），覆盖本接口全部接入点。 - 可导入 **Postman / Swagger UI / Swagger Editor** 管理接口、自动生成请求模板与 Mock。 - 鉴权为 query 参数 `appKey`，导入后在请求里填上你的 AppKey 即可调试。 ## Why：为什么要用 OpenAPI 管接口 接口契约集中在一份 OpenAPI 文档里，团队就能用统一工具调试、生成 Mock、做契约测试，新人也能照文档快速上手。比"口头传参数、各自存代码片段"可靠得多。本接口官方就提供了规范 YAML，直接拿来用即可。 ## What：文档与资源 | 资源 | 地址 | |------|------| | OpenAPI YAML | https://www.showapi.com/openapi/market/2219.yaml | | OpenAPI JSON | https://www.showapi.com/openapi/market/2219.json | | 接口详情页 | https://www.showapi.com/apiGateway/view/2219 | | AppKey 管理 | https://www.showapi.com/console#/myApp | 文档要点（来自官方 YAML）：路径 `/2219-1`，参数 `sx`（必填）、`needTomorrow`、`needMonth`（选填），鉴权 `AppKeyAuth`（apiKey，位于 query 的 `appKey`），返回为 ShowAPI 统一包裹 `ShowapiResEnvelope` + 业务体。 ## How：导入到 API 工具 ### ① 导入 Postman 1. 打开 Postman，新建/选择集合 → **Import**。 2. 粘贴 YAML 地址 `https://www.showapi.com/openapi/market/2219.yaml`，或先下载再选文件导入。 3. 导入后自动生成请求：`POST /2219-1`，参数面板含 `sx`/`needTomorrow`/`needMonth`。 4. 在请求 URL 或 Params 里填入 `appKey=你的真实AppKey`，`sx=hou`，点 Send 即可看到返回。 ### ② 在线用 Swagger UI / Swagger Editor - Swagger Editor：打开 https://editor.swagger.io/ ，把 YAML 内容粘贴进去，右侧即渲染可交互文档，可直接"Try it out"填参调试。 - Swagger UI：若有自建 UI，把 YAML 托管为静态文件后指向它，团队成员即可在网页上读文档并调试。 无论哪种，鉴权位置都是 **query 参数 `appKey`**，不要填到 Header 或 Body（本接口 AppKey 走 query）。 ## 返回示例与解析 OpenAPI 文档定义的返回结构与本文其他篇一致：`showapi_res_code`/`showapi_res_error`/`showapi_res_id` 系统包裹 + `showapi_res_body`（含 `ret_code`/`remark`/`shenxiao`/`day`/`month`/`tomorrow`）。字段细节见《[生肖运势查询：返回字段全解](https://www.showapi.com/guides/shengxiao-fortune-response-fields-2219)》。 ## 进阶 / 边界 - **Mock 数据**：Swagger UI / Postman 都能基于 schema 生成 Mock，但 Mock 返回的是结构占位、非真实运势，仅用于前端联调，真实数据仍要带 AppKey 调易源。 - **契约即文档**：把 OpenAPI 文档纳入版本管理，接口变更以文档为准，避免团队各执一份过时说明。 - **不要自造路径**：参数页真实入口是 `/apiGateway/view/2219` 或 `/2219/1`；不要拼 `/apiGateway/view/{字母}` 这类软 404 路径。 ## FAQ **Q1：OpenAPI 文档是最新的吗？** A：文档由易源官方 OpenAPI 生成器产出（示例生成时间 2026-08-26），以线上 YAML 为准；若接口有变动以官方最新 YAML 为准。 **Q2：appKey 应该填在哪？** A：本接口 AppKey 是 query 参数（`AppKeyAuth`，in: query，name: appKey）。导入工具后在请求 URL 或 Query Params 填，不要放 Header/Body。 **Q3：导入后报错"schema 不合法"？** A：先确认导入的是官方 YAML/JSON 原文件，未手工改动结构；Postman/Swagger 对 3.0.x 均原生支持，遇报错多数源于复制时格式损坏。 **Q4：Mock 返回的运势是真的吗？** A：不是。Mock 只按 schema 生成结构占位，用于前端联调；真实运势必须带有效 AppKey 调易源接口获取。 **Q5：能基于这份文档做自动化测试吗？** A：可以。OpenAPI 是契约测试的事实标准，可用 Postman Collection Runner 或基于 OpenAPI 的测试框架，对 `ret_code`/`day` 字段做断言。 ## 相关能力 / 下一步阅读 - [生肖运势查询：通过 MCP 在 Cherry Studio / ChatBox 等 AI 客户端直接调用](https://www.showapi.com/guides/shengxiao-fortune-mcp-2219) - [生肖运势查询：5 分钟接入，从注册到第一条运势结果](https://www.showapi.com/guides/shengxiao-fortune-quickstart-2219) - [生肖运势查询：返回字段全解（day / month / tomorrow 三大对象差异与指数说明）](https://www.showapi.com/guides/shengxiao-fortune-response-fields-2219) - **本系列共 9 篇**：查看[生肖运势查询指南总目录](https://www.showapi.com/guides/shengxiao-fortune-guides-2219)