导入 Postman / Swagger：用 OpenAPI 文档管理健康知识接口
健康知识OpenAPIPostmanSwagger # 导入 Postman / Swagger：用 OpenAPI 文档管理健康知识接口
- **接口/接入点**：健康知识（OpenAPI 3.0 文档，覆盖全部 3 个接入点，免费）
- **文档格式**：OpenAPI 3.0（YAML / JSON） ｜ **适用人群**：API 治理 / 团队协作者
- **阅读时间**：约 6 分钟
## 核心要点
- 健康知识接口提供标准的 OpenAPI 3.0 文档，覆盖全部 3 个接入点，可导入 API 工具做管理与 Mock。
- 推荐用 **Postman / Swagger UI / Swagger Editor** 导入，自动生成请求模板与 Mock 数据。
- 借助 OpenAPI 文档，团队可以统一接口契约、生成客户端代码、做联调与回归。
## Why：用 OpenAPI 把接口纳入资产
当团队多人协作、或要把健康知识接口封装进自己的服务/低代码平台时，仅靠网页文档容易信息分散、版本漂移。OpenAPI 文档是机器可读的接口契约：导入 Postman 可一键生成请求模板，导入 Swagger UI 可在线调试，导入 Swagger Editor 可做编辑与校验。一份文档，多处复用。
## What：文档获取
| 项目 | 地址 |
|------|------|
| OpenAPI YAML | `https://www.showapi.com/openapi/market/90.yaml` |
| OpenAPI JSON | 同路径（接口详情页「OpenAPI 文档」处提供 YAML 与 JSON 两种格式） |
| 接口详情页 | `https://www.showapi.com/apiGateway/view/90` |
该文档为接口级，覆盖分类列表（`90-86`）、搜索知识（`90-87`）、查看单条详情（`90-88`）三个接入点。
## How：导入到 Postman / Swagger
### 方式一：Postman
1. 打开 Postman，选择「Import」；
2. 粘贴或上传 YAML 地址 `https://www.showapi.com/openapi/market/90.yaml`；
3. 导入后自动生成三个接入点的请求集合，每个请求已带好路径与参数定义；
4. 在请求的 URL 中填入你的 `appKey`（`?appKey=YOUR_APPKEY`）即可发送。
### 方式二：Swagger UI
1. 打开 Swagger UI（自托管或官方在线版）；
2. 通过「Explore」/「URL」加载 `https://www.showapi.com/openapi/market/90.yaml`；
3. 页面直接展示三个接入点的参数与 Schema，可在线「Try it out」调试。
### 方式三：Swagger Editor
1. 打开 Swagger Editor；
2. 通过「File → Import URL」导入上述 YAML；
3. 可编辑、校验 Schema，并导出为客户端代码（OpenAPI Generator 生态）。
## 返回示例与解析（来自 OpenAPI Schema）
OpenAPI 文档中定义的搜索知识返回结构（节选）：
```yaml
showapi_res_body:
properties:
ret_code:
type: string
description: 成功标志 0为成功 其它失败
pagebean:
type: object
properties:
allNum: { type: number, description: 总条数 }
allPages: { type: number, description: 页面数 }
maxResult: { type: number, description: 每页最大数 }
contentlist:
type: array
items:
type: object
properties:
id: { type: string, description: 知识文章id }
title: { type: string, description: 标题 }
tname: { type: string, description: 分类名称 }
ctime: { type: string, description: 发布时间 }
```
## 进阶 / 边界
- **appKey 不进文档**：OpenAPI 文档描述的是接口契约，鉴权用的 `appKey` 由你在请求时填入，不要写进共享的文档文件。
- **Mock 数据**：Swagger UI / Postman 可基于 Schema 生成示例响应，适合前端在后端未联调时并行开发。
- **版本**：本文档为 `generated-at 2026-08-26` 的版本；如接口更新，以官方最新文档为准。
## FAQ
**Q：OpenAPI 文档覆盖全部接入点吗？**
A：是的，该 OpenAPI 文档为接口级，覆盖分类列表、搜索知识、查看单条详情三个接入点。
**Q：导入后为什么请求报错？**
A：先确认已在 URL 中填入有效的 `appKey`；再检查请求方式（POST/GET 均可）与表单参数是否按要求传递。
**Q：可以用 OpenAPI 生成客户端代码吗？**
A：可以。Swagger Editor 及 OpenAPI Generator 生态支持根据 YAML 生成多种语言的客户端 SDK，便于团队统一调用层。
**Q：文档会和网页文档不一致吗？**
A：两者同源，以官方最新发布为准；如发现差异，以接口详情页与 OpenAPI 文档共同描述的事实为准。
## 相关能力与下一步阅读
- [健康知识 API：5 分钟接入，获取每日健康养生内容](https://www.showapi.com/guides/health-knowledge-quickstart-90)
- [健康知识 API 返回字段全解：分类列表 / 搜索结果 / 知识详情三大结构](https://www.showapi.com/guides/health-knowledge-fields-90)
- [通过 MCP 协议在 AI 客户端中直接查询健康知识](https://www.showapi.com/guides/health-knowledge-mcp-90)
- **本系列共 12 篇**：查看[健康知识 API 使用指南总目录](https://www.showapi.com/guides/health-knowledge-guides-90)
