导入 Postman / Swagger：用 OpenAPI 文档管理常见疾病查询接口
# 导入 Postman / Swagger：用 OpenAPI 文档管理常见疾病查询接口
> 接口：常见疾病查询（apiCode=546）· 免费 · OpenAPI 3.0 · 返回格式 JSON · 适用人群：注重 API 治理的团队 · 阅读时间：约 5 分钟
## 核心要点
- 常见疾病查询提供标准 **OpenAPI 3.0** 文档，覆盖全部 3 个接入点：YAML / JSON 双格式。
- 可导入 **Postman / Swagger UI / Swagger Editor**，自动生成请求模板与 Mock，便于团队协作与调试。
- 文档亦可供 AI Agent 直接消费（与 [MCP](https://www.showapi.com/guides/disease-query-mcp-546) 互补）。
> 注：本文仅使用 Postman / Swagger 等通用工具表述；不涉及其他 API 调试工具。
## Why：用 OpenAPI 做接口治理
当团队多人对接常见疾病查询，最怕"每个人手里的参数表不一样"。OpenAPI 文档是单一事实源：导入后自动生成可点即发的请求、参数说明、响应结构，新人照着填就能调通；也能生成 Mock 供前端并行开发。对需要 API 治理的团队，这是标准做法。
## What：OpenAPI 资源
| 格式 | 地址 |
|------|------|
| YAML | https://www.showapi.com/openapi/market/546.yaml |
| JSON | https://www.showapi.com/openapi/market/546.json |
文档含 3 个 path：`/546-1`、`/546-2`、`/546-3`，鉴权为 query 参数 `appKey`，响应结构见[返回字段全解](https://www.showapi.com/guides/disease-query-response-fields-546)。
## How：导入到工具
### 导入 Postman
1. 打开 Postman → 左上角 **Import**。
2. 选择 **Link** 方式，粘贴 `https://www.showapi.com/openapi/market/546.yaml`（或下载 YAML 后选 File 导入）。
3. 导入后生成包含 546-1/546-2/546-3 的集合；在请求里把 `appKey` 设为你的真实值即可发送。
4. 可用 Postman 的「Examples / Mock Server」基于响应结构生成 Mock，供前端联调。
### 用 Swagger UI 在线预览
1. 打开 Swagger UI（自建或公开实例）。
2. 粘贴 YAML 地址或上传文件，即可交互式浏览三接入点的参数与响应 Schema。
3. 直接在页面 **Try it out** 填 `appKey` 与参数发起调用。
### 用 Swagger Editor 编辑/生成
1. 打开 Swagger Editor，导入 YAML。
2. 可查看/微调文档，并生成客户端 SDK 或多语言调用骨架。
### cURL（从文档直接拿）
```bash
curl -X POST "https://route.showapi.com/546-2?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
--data-urlencode "key=高血压" --data-urlencode "page=1"
```
### Node.js（fetch，基于文档 Schema）
```javascript
const resp = await fetch("https://route.showapi.com/546-2?appKey=YOUR_APPKEY", {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ key: "高血压", page: "1" }).toString(),
});
const data = await resp.json();
console.log(data.showapi_res_body.contentlist);
```
## 返回示例与解析
OpenAPI 文档的 `responses` 已定义 `showapi_res_body` 的 Schema（含 `ret_code`、列表/明细结构），Swagger UI 会直接渲染字段说明，无需你手查。
## 进阶 / 边界
- **文档覆盖全部接入点**：一份 YAML 同时含 546-1/546-2/546-3，导入即全有。
- **Mock 仅结构**：工具生成的 Mock 返回的是 Schema 示例，非真实数据；要真实数据仍走实际接口。
- **与 MCP 互补**：OpenAPI 适合人/团队治理与前端联调；MCP 适合 AI Agent 自动调用（见[MCP 集成](https://www.showapi.com/guides/disease-query-mcp-546)）。
- **文档版本**：以官方 YAML/JSON 实时地址为准，变化时重新导入即可。
## FAQ
**Q1：YAML 和 JSON 用哪个？**
A：内容一致，按工具习惯选；Postman/Swagger 多支持 YAML，直接贴链接最方便。
**Q2：导入后还要自己写鉴权吗？**
A：文档定义鉴权为 query 参数 `appKey`，导入后在请求里填真实 AppKey 即可。
**Q3：Mock 返回的是真实疾病数据吗？**
A：不是。Mock 是结构示例，真实数据需调用实际接口。
**Q4：三个接入点都在一份文档里吗？**
A：是。546-1/546-2/546-3 同在一份 OpenAPI 文档，导入即全含。
## 相关能力 / 下一步阅读
- [通过 MCP 在 Cherry Studio / ChatBox 中直接调用常见疾病查询](https://www.showapi.com/guides/disease-query-mcp-546)
- [常见疾病查询返回字段全解：科目树、疾病列表与明细结构一文读懂](https://www.showapi.com/guides/disease-query-response-fields-546)
- [常见疾病查询：5 分钟从注册到拿到第一篇疾病明细](https://www.showapi.com/guides/disease-query-quickstart-546)
- **本系列共 12 篇**：查看[常见疾病查询指南总目录](https://www.showapi.com/guides/disease-query-guides-546)
