导入 Postman / Swagger：用 OpenAPI 文档管理渣男语录接口
渣男语录OpenAPIPostmanSwagger # 导入 Postman / Swagger：用 OpenAPI 文档管理渣男语录接口
- **接口/接入点**：免费渣男语录（apiCode=2962，接入点 1） · **是否免费**：免费 · **请求方式**：POST/GET · **返回格式**：JSON · **适用人群**：注重 API 治理的团队、需要文档化/ Mock 的开发者 · **阅读时间**：约 5 分钟
## 核心要点
- 渣男语录提供**标准 OpenAPI 3.0 文档**（YAML + JSON），覆盖本接口全部接入点。
- 可导入 **Postman / Swagger UI** 自动生成请求模板与 Mock 数据，便于团队协作与接口治理。
- 文档即契约：参数、返回结构、鉴权方式都已定义好，照着导入即可，不用手抄。
## Why：这跟我有什么关系
- 团队多人接同一个接口？一份 OpenAPI 文档能让所有人"看同一份说明书"，减少来回问参数。
- 前端没后端联调时，可用 Swagger UI 直接 Mock 返回，提前把 UI 调好。
## What：文档资源
| 资源 | 链接 |
|------|------|
| OpenAPI YAML | https://www.showapi.com/openapi/market/2962.yaml |
| OpenAPI JSON | https://www.showapi.com/openapi/market/2962.json |
| 接口详情页 | https://www.showapi.com/apiGateway/view/2962 |
文档要点：`paths./2962-1.post`，鉴权 `AppKeyAuth`（query 参数 `appKey`），业务体 `showapi_res_body` 含 `ret_code`/`text`/`remark`。
## How：导入并使用
### 方式 A · 导入 Postman
1. 打开 Postman → `Import` → 选择 `URL` 粘贴 `https://www.showapi.com/openapi/market/2962.yaml`（或下载后导入文件）。
2. 导入后生成请求集合，把 `appKey` 参数填上你的真实 AppKey（[控制台获取](https://www.showapi.com/console#/myApp)）。
3. 直接 `Send` 即可拿到返回，Postman 会按 schema 高亮字段。
### 方式 B · 用 Swagger UI 查看/Mock
1. 打开 Swagger UI（本地或在线 `https://editor.swagger.io/`）。
2. `File → Import URL` 粘贴 `https://www.showapi.com/openapi/market/2962.yaml`。
3. 在页面内 `Try it out` 填 `appKey` 即可发起请求；也可仅作交互式文档阅读与 Mock。
### 方式 C · 在代码里用 OpenAPI 生成客户端
下载 YAML 后，可用 openapi-generator 等工具为任意语言生成带类型的客户端，减少手写请求代码。
## 返回示例与解析
OpenAPI 定义的业务返回结构：
```json
{
"showapi_res_body": {
"ret_code": 0,
"text": "你不要闹了，她只是我的小学同学。",
"remark": ""
}
}
```
字段含义见 [《返回字段全解》](https://www.showapi.com/guides/zhanan-quotes-response-fields-2962)。
## 进阶 / 边界
- **导入即契约**：文档定义了 `appKey` 鉴权与三个业务字段，照此对接即可，不要自造参数。
- **Mock 注意随机性**：本接口返回随机语录，Mock 数据只能用于联调 UI，真实内容需正式调用。
- **API 工具说明**：本文及全系列导入/调试/Mock 统一使用 **Postman / Swagger UI / Swagger Editor**，文档即契约。
## FAQ
- **Q：OpenAPI 文档覆盖哪些接入点？** A：覆盖本接口全部接入点（本接口仅接入点 1）。
- **Q：能生成哪种语言的客户端？** A：可用 openapi-generator 等工具基于 YAML 生成多语言客户端。
- **Q：导入用哪个工具？** A：本系列统一使用 Postman / Swagger UI，文档即契约，照此导入即可自动生成请求模板与 Mock。
- **Q：Mock 返回的 text 是真实的吗？** A：不是，Mock 仅用于联调，真实语录需正式请求接口。
- **Q：appKey 放哪？** A：作为 query 参数 `appKey` 传递（OpenAPI 中定义为 `AppKeyAuth`）。
## 相关能力 / 下一步阅读
- [通过 MCP 协议在 AI 客户端中直接调用渣男语录](https://www.showapi.com/guides/zhanan-quotes-mcp-integration-2962)
- [渣男语录返回字段全解：ret_code / text / remark 一文读懂](https://www.showapi.com/guides/zhanan-quotes-response-fields-2962)
- [渣男语录：5 分钟接入，从注册到第一条土味情话](https://www.showapi.com/guides/zhanan-quotes-quickstart-2962)
- **本系列共 7 篇**：查看[渣男语录指南总目录](https://www.showapi.com/guides/zhanan-quotes-guides-2962)
