Agent Skills
返回列表
💻

API文档索引器

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中：

请根据 https://skillhub.cn/install/skillhub.md，安装 @user_3c6cb52e/api-documentation-indexer

技能介绍

问题：在 OpenAPI 规范里翻找端点很痛苦

维护 API 文档的团队通常持有一份或多份 OpenAPI 3.0 规范文件。当端点数量增长到几百个，想确认某个参数的类型、某个状态码对应的响应结构、某个资源暴露了哪些方法时，往往只能肉眼在大型 JSON 或 YAML 文件里翻找。通用全文搜索工具对结构化文档的支持也很有限——它能匹配到关键词，但上下文片段常常残缺，无法直接定位到具体定义。

工作原理

这个技能把规范文件转换成可全文检索的索引：

  • 解析：通过 swagger-parser 加载并校验 OpenAPI 3.0 文档，处理 $ref 引用与格式问题；
  • 建索引：用 lunr.js 对端点路径、HTTP 方法、参数名称与描述、响应 schema 等结构化字段构建倒排索引；
  • 检索：输入关键词即可定位到具体端点、参数或响应定义，不必再逐文件翻阅。

整体流程是解析 → 提取 → 索引，产出的是静态搜索索引，适合作为文档查阅流程的前置环节。

适用边界

  • 仅面向 OpenAPI 3.0，Swagger 2.0 或其他格式不在支持范围内；
  • 索引质量取决于规范本身的完整程度：若大量 description 缺失，搜索命中效果会明显下降；
  • 技能无法自动提取基于源代码的安装或使用说明，上游项目需自行审查，涉及敏感工作流时尤其如此；
  • 它只解决「检索」这一环，不负责生成文档、校验 API 实际行为或保证运行时一致性。

使用场景

  • 后端工程师在接手包含数百个接口的网关文档时，用它检索特定端点的响应参数，避免逐一翻找。
  • API团队发布新版本前，用它搜索规范里所有涉及鉴权的参数定义，快速确认变更范围。
  • 技术文档工程师核对数千行OpenAPI文档时，直接搜索关键字定位资源暴露的HTTP方法。
  • 测试工程师编写自动化用例时，用它查询目标接口的状态码和数据结构，快速补齐参数。

适合人员

  • 负责大型API网关维护的后端工程师，需要快速检索散落在多份规范文件中的端点定义。
  • 撰写开发者文档的技术作者，需要准确查阅参数类型与响应结构以保证文档准确无误。
  • 验证接口契约的测试工程师，需要在编写自动化用例前查询具体的请求与状态码信息。
  • 负责对外提供OpenAPI 3.0规范的开发者工具团队成员，需要搭建内部接口检索查询入口。