Agent Skills
返回列表
💻

GraphQL 模式文档生成器

开发编程 更新于 2026.08.29

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

请根据官方安装指南 https://skillhub.cn/install/skillhub.md，将 @user_3c6cb52e/graphql-schema-documentation-generator 安装到当前 AI 助手中。

技能介绍

解决什么问题

GraphQL 项目的 API 文档往往散落在代码注释、Wiki 页面和口头约定里。模式里新增了字段，文档没同步；客户端想知道某个字段有没有人用，还得翻查询日志。维护一份"活的"文档，成本不低。

核心能力与工作流程

这个技能基于 graphql-js 的标准内省查询（introspection），直接从 GraphQL 模式定义中提取字段、类型和关系信息，再交给 SpectaQL 渲染成交互式文档页面。具体步骤：

  • 运行 graphql-js 内省查询，读取模式的完整结构
  • 将模式数据传给 SpectaQL，生成带搜索和导航的文档 UI
  • 通过 Apollo Studio API 拉取字段级使用分析数据，为每个字段标注调用频次等指标

这样产出的文档不是静态快照，而是随模式更新的工具链产物。

适用边界与注意点

  • 依赖 Node.js 环境：graphql-js 同时支持 CommonJS（require()）和 ESModule（import），确保项目中两种模块风格混用时配置正确
  • Apollo Studio 数据：字段使用分析需要有 Apollo Studio 项目接入，否则只能生成纯模式文档
  • 模式变更频率：每次模式变更后需重新生成，文档不会自动热更新

使用场景

  • GraphQL 模式刚更新，需要重新生成一份与代码保持同步的交互式 API 文档
  • 想清理模式里长期没人调用的冗余字段，需要先确认各字段的真实使用情况
  • 项目已接入 Apollo Studio，想把每个字段的调用频次直接标注在文档页面上

适合人员

  • 后端工程师：GraphQL 模式迭代频繁，需要低成本维护始终最新的 API 文档
  • 技术文档工程师：要把模式结构整理成带搜索与导航的文档页面，不想手写 Markdown
  • API 平台负责人：想依据字段使用分析做 API 治理，逐步淘汰低使用率字段