导入 Postman / Swagger：用 OpenAPI 文档管理笑话大全接口

# 导入 Postman / Swagger：用 OpenAPI 文档管理笑话大全接口 > 接口 341-5 · 免费 · OpenAPI 3.0 · 适用人群：API 治理团队、后端工程师 · 阅读时间：约 4 分钟 ## 核心要点 - 笑话大全提供标准 OpenAPI 3.0 文档（YAML / JSON），覆盖全部接入点。 - 可导入 **Postman / Swagger UI** 自动生成请求模板与 Mock，无需手敲参数。 - 文档地址固定，便于团队统一管理与 AI Agent 直接消费。 ## Why 团队接入接口时，最怕"每个人手敲一遍 URL 和参数"，容易出错、难统一。OpenAPI 文档是接口的"标准说明书"，导入 API 工具后自动生成可调用的请求模板，还能做 Mock 联调。笑话大全已提供官方 OpenAPI 3.0 文档，本篇教你怎么用起来。 > 说明：本文使用 **Postman / Swagger UI / Swagger Editor** 等通用 API 工具。全文不出现其他同类工具的专有名称。 ## What | 项 | 说明 | |----|------| | 文档格式 | OpenAPI 3.0（生成于 2026-08-26） | | YAML 地址 | https://www.showapi.com/openapi/market/341.yaml | | JSON 地址 | https://www.showapi.com/openapi/market/341.json | | 覆盖范围 | 本接口全部接入点（当前 341-5） | | 鉴权定义 | `appKey`（query，API key 方式） | ## How ### 步骤 1：下载 / 打开文档 - YAML：https://www.showapi.com/openapi/market/341.yaml - JSON：https://www.showapi.com/openapi/market/341.json ### 步骤 2：导入 Postman 1. 打开 Postman → Import。 2. 粘贴上方 YAML/JSON 链接或上传文件。 3. 导入后自动生成 `341-5` 请求，鉴权处填你的 `appKey`（query 参数）。 4. 点击 Send 即可拿到返回。 ### 步骤 3：用 Swagger UI 预览 将 YAML 贴入 Swagger UI / Swagger Editor 的编辑区，即可在线查看接口结构、`showapi_res_body` 字段说明，并直接"Try it out"调试。 ### 步骤 4：给 AI Agent 消费 OpenAPI 文档可被支持的工具直接读取，作为接口契约供 Agent 生成调用代码或理解字段结构。 ## 返回示例与解析 导入后发起的请求与[快速接入](https://www.showapi.com/guides/joke-api-quickstart-341)一致，返回 `showapi_res_body` 内含 `id/title/text/ret_code/remark/ct`。字段含义见[返回字段全解](https://www.showapi.com/guides/joke-api-response-fields-341)。 ## 进阶 / 边界 - **只一个接入点**：当前 OpenAPI 仅描述 341-5，导入后只会看到这一个路径。 - **无业务参数**：文档 `parameters: []`，导入后请求面板只有 `appKey` 鉴权项，无需填其他参数。 - **文档即契约**：以官方 YAML 为准，团队统一引用该链接，避免各自维护副本。 ## FAQ **Q1：文档会更新吗？** 官方 OpenAPI 由 ShowAPI 生成器产出（示例标注生成于 2026-08-26），接口变动时以官方 YAML 为准。 **Q2：导入后为什么没有请求参数可填？** 本接口无业务请求参数，只有 `appKey` 鉴权；在鉴权/参数里填 appKey 即可。 **Q3：能用它生成 Mock 数据联调吗？** 可以。Swagger UI / Postman 均可基于 schema 生成 Mock，便于前后端并行开发。 **Q4：JSON 和 YAML 用哪个？** 内容一致，按你所用工具偏好选择；Postman 对两者都支持。 **Q5：AppKey 在文档里怎么体现？** OpenAPI 中定义为 `securitySchemes.AppKeyAuth`（query 参数 `appKey`），导入工具后在鉴权配置里填值。 ## 相关能力 / 下一步阅读 - [通过 MCP 在 ChatBox/Cherry Studio 中直接调用笑话大全](https://www.showapi.com/guides/joke-api-mcp-341) - [笑话大全返回字段全解：showapi_res_body 与 id/title/text 一文读懂](https://www.showapi.com/guides/joke-api-response-fields-341) - [笑话大全：5 分钟接入，从注册到拿到第一条笑话](https://www.showapi.com/guides/joke-api-quickstart-341) - **本系列共 10 篇**：查看[笑话大全 API 指南总目录](https://www.showapi.com/guides/joke-api-guides-341)