导入 Postman / Swagger：用 OpenAPI 文档管理童话故事集 API
OpenAPIPostmanSwaggerAPI治理 # 导入 Postman / Swagger：用 OpenAPI 文档管理童话故事集 API
> 元信息：童话故事集 API（apiCode=1700）· 集成能力 OpenAPI 3.0 · 免费服务 · 适用人群：注重 API 治理的团队 · 阅读时间约 6 分钟
## 核心要点
- 童话故事集 API 提供标准 OpenAPI 3.0 文档，覆盖全部 3 个接入点，可用于导入 API 工具、生成请求模板与 Mock。
- 文档地址：YAML `https://www.showapi.com/openapi/market/1700.yaml`、JSON `https://www.showapi.com/openapi/market/1700.json`。
- 可导入 Postman / Swagger UI / Swagger Editor 进行调试、文档沉淀与团队协作（不依赖特定商业工具）。
## Why：用 OpenAPI 把接口管起来
当团队开始依赖童话故事集 API，零散的 curl 片段会越来越难维护。OpenAPI 文档把三个接入点的路径、参数、返回结构标准化描述，导入 API 工具后即可自动生成请求模板、在线调试与 Mock 数据，也方便写进团队的 API 目录。本篇讲清怎么下载并导入。
## What：OpenAPI 速览
| 项目 | 说明 |
|------|------|
| 规范 | OpenAPI 3.0 |
| 覆盖范围 | 接口 1700 全部接入点 |
| YAML | https://www.showapi.com/openapi/market/1700.yaml |
| JSON | https://www.showapi.com/openapi/market/1700.json |
| 适用工具 | Postman、Swagger UI、Swagger Editor |
## How：下载并导入
### 1. 下载文档
```bash
curl -O https://www.showapi.com/openapi/market/1700.yaml
# 或 JSON 版本
curl -O https://www.showapi.com/openapi/market/1700.json
```
### 2. 导入 Postman
1. 打开 Postman，选择「Import」。
2. 选择下载的 `1700.yaml`（或 `1700.json`）。
3. Postman 会自动生成对应集合，包含三个接入点的请求模板。
4. 在请求 URL 的 `appKey` 处填入你的真实 AppKey（https://www.showapi.com/console#/myApp），即可发送调试。
### 3. 用 Swagger UI / Swagger Editor 在线查看
- Swagger UI：将 `1700.yaml` 内容粘贴/加载到 Swagger UI，即可在线浏览各接入点参数与示例、直接 Try it out。
- Swagger Editor：打开编辑器加载该 YAML，可校验规范、生成客户端代码与 Mock Server。
```javascript
// 团队自研平台也可直接消费 JSON 版做渲染
const spec = await (await fetch("https://www.showapi.com/openapi/market/1700.json")).json();
console.log(Object.keys(spec.paths)); // 查看覆盖的接入点路径
```
## 返回示例与解析
OpenAPI 文档本身描述的就是各接入点的请求/响应结构，与你用代码调用得到的 JSON 一致（见[返回字段全解](https://www.showapi.com/guides/child-story-fields-1700)）。文档里 `appKey` 作为 query 参数出现，调试时替换为你自己的 AppKey 即可。
## 进阶 / 边界
- **appKey 不要进版本库**：OpenAPI 文件若被团队共享，记得把示例里的 AppKey 用占位符，真实密钥走环境变量/密钥管理。
- **文档与实时返回以接口为准**：若 OpenAPI 描述与接口实际返回有出入（如字段命名），以接口实时返回为准，并可向官方反馈。
- **Mock 仅用于联调**：用 Swagger 生成的 Mock 数据是结构占位，不是真实故事内容，联调后仍需对接真实接口。
## FAQ
**Q: 这个 OpenAPI 文档覆盖哪几个接入点？**
A: 覆盖接口 1700 全部接入点：故事分类(1700-1)、故事列表(1700-2)、故事详情(1700-3)。
**Q: 导入后为什么请求失败？**
A: 多半是 `appKey` 未替换或无效。确认用的是你自己应用下的有效 AppKey，且接口未触发免费档位限制。
**Q: 能不能生成各语言 SDK？**
A: OpenAPI 文档可被多种代码生成器消费来生成客户端骨架；具体生成能力取决于你选用的工具链。
**Q: 文档里的示例能直接当正式数据用吗？**
A: 不能。示例/Mock 仅用于结构联调，正式内容需调用真实接口获取。
## 相关能力 / 下一步阅读
- [通过 MCP 在 AI 客户端里直接调用童话故事集 API](https://www.showapi.com/guides/child-story-mcp-1700)
- [童话故事集 API 返回字段全解](https://www.showapi.com/guides/child-story-fields-1700)
- [童话故事集 API：5 分钟接入](https://www.showapi.com/guides/child-story-quickstart-1700)
- **本系列共 12 篇**：查看[童话故事集 API 指南总目录](https://www.showapi.com/guides/child-story-guides-1700)
