OpenAPI 读取器

要解决的问题

在让大模型帮你改接口、写调用示例或排查联调问题时，最常见的卡点不是模型能力不够，而是 上下文装不下整份接口文档。一份 OpenAPI 文档动辄几十到几百 KB，包含数百个路径、大量 schema 与枚举，直接塞进对话要么被截断，要么模型在长文里丢失关键约束。另一个问题是结构不统一：不同团队产出的文档，有的用 JSON，有的用 YAML，字段命名与描述完备程度也参差不齐，人工梳理成本很高。

核心能力与关键步骤

OpenAPI Reader 把「读取 OpenAPI 文档」这件事做成技能，工作流大致分三步：

• 定位文档：从项目中找到 openapi.json、openapi.yaml 或指定路径的规范文件，按实际位置读取，不做固定假设。
• 结构化提取：按文档自身的结构解析 paths、operations、parameters 与 components/schemas，把分散的定义归位，而不是把原文整段贴给模型。
• 按需输出：返回可读的接口清单或摘要，保留方法、路径、参数、响应等关键字段，便于后续继续让模型推理。

这样做的收益是：模型只拿到它真正需要的那部分结构，而不是在长文档里大海捞针。

适用边界与注意点

• 它解决的是读取与理解，不负责生成服务端代码，不做请求重放，也不是接口测试工具。
• 文档本身描述不全（缺 description、没有示例）时，读取结果会继承这些缺陷，关键接口仍建议对照真实服务确认。
• 若文档使用了非标准扩展，自定义字段能否保留取决于文档写法，使用前建议抽查。
• 超大文档建议先按需读取片段，避免一次加载超出上下文预算。