藏头诗生成：导入 Postman / Swagger UI 管理你的接口

# 藏头诗生成：导入 Postman / Swagger UI 管理你的接口 > 接口/接入点：藏头诗生成（apiCode=950，接入点 950-1）· 免费 · 提供 OpenAPI 3.0 文档 · 适用人群：注重 API 治理的团队、开发者 · 阅读时间：6 分钟 ## 核心要点 - 官方提供标准 OpenAPI 3.0 文档（YAML/JSON），覆盖本接口全部接入点。 - 可导入 **Postman / Swagger UI（及 Swagger Editor）** 生成请求模板与 Mock 数据。 - 注意：OpenAPI 文档本身兼容多种工具，Postman / Swagger 已足够完成接口治理与联调。 ## Why：把接口文档变成可执行的"活资产" 有了 OpenAPI 文档，团队不用手动拼参数，导入工具即可自动生成带鉴权位的请求模板、做 Mock、做联调。对多人对接、持续集成的场景尤其省事。 ## What：OpenAPI 文档资源 | 资源 | 链接 | |------|------| | OpenAPI YAML（在线/下载） | https://www.showapi.com/openapi/market/950.yaml | | OpenAPI JSON | https://www.showapi.com/openapi/market/950.json | 文档要点（已校验）：路径 `/950-1`，`application/x-www-form-urlencoded` 请求体，必填 `num`/`type`/`yayuntype`/`key`，鉴权为 query 参数 `appKey`，返回含 `showapi_res_body`（list/ret_code）。 ## How：导入工具 **Postman** 1. 打开 Postman → Import → 选择 `Link` 粘贴 `https://www.showapi.com/openapi/market/950.yaml` → 导入。 2. 导入后自动生成 `950-1` 请求，把 `appKey` query 参数填为你的真实 AppKey。 3. 在 Body（x-www-form-urlencoded）填入 `num=5&type=1&yayuntype=1&key=易源接口`，Send 即可看到返回。 **Swagger UI / Swagger Editor** 1. 打开 Swagger UI 或 Swagger Editor，粘贴 YAML 内容（或指向上述 YAML 链接）。 2. 文档会渲染出 `POST /950-1` 及参数表，直接在页面 Try it out 填参调试。 3. 可用于团队共享接口定义、生成 Mock Server。 **cURL 取文档（便于存档）** ```bash curl -o cangtoushi-950.yaml "https://www.showapi.com/openapi/market/950.yaml" ``` ## 返回示例与解析 导入后发起的请求与直接调用一致，返回结构见[返回字段全解](https://www.showapi.com/guides/cangtoushi-response-fields-950)（`showapi_res_body.list` 为诗句数组）。 ## 进阶 / 边界 - 文档标注 `x-read-timeout:30` / `x-connect-timeout:30`，工具里可据此设 30s 超时。 - OpenAPI 将 `list` 标为 string，但实测返回为数组，治理/校验时按数组处理。 - 如团队只用 Postman / Swagger 即满足接口治理需求，无需其他工具。 ## FAQ **Q1：文档能导入哪些工具？** OpenAPI 3.0 通用，可导入 Postman、Swagger UI、Swagger Editor 等。 **Q2：需要自己写鉴权吗？** 鉴权是 query 参数 `appKey`，导入后填真实 AppKey 即可。 **Q3：能生成 Mock 数据吗？** 可以，Swagger UI / Postman 均支持基于 schema 的 Mock。 **Q4：list 类型不一致怎么办？** 以实际返回（数组）为准，schema 标注偏差不影响调用。 ## 相关能力 / 下一步阅读 - [藏头诗生成：通过 MCP 在 Cherry Studio / ChatBox 直接生成](https://www.showapi.com/guides/cangtoushi-mcp-950) - [藏头诗生成：返回字段全解（list / ret_code / showapi_res_*）](https://www.showapi.com/guides/cangtoushi-response-fields-950) - **本系列共 12 篇**：查看[藏头诗生成指南总目录](https://www.showapi.com/guides/cangtoushi-guides-950)