GraphQL 内省文档生成器

解决什么问题

GraphQL 服务通常自带内省能力，但拿到的 __schema 原始返回对工程师并不友好：几百个 type 平铺在一起，interface、union、自定义 scalar 的语义混在 JSON 里，字段说明也常常缺失。手写文档要么很快过期，要么只覆盖查询入口，内部的类型关系全靠翻源码。这个技能针对的就是「schema 本身可查、文档却缺失或滞后」这一常见缺口：直接向目标端点发起内省查询，再用 graphql-js 的类型系统把结果整理成结构化的 API 文档。

核心能力与关键步骤

1. 向目标 GraphQL endpoint 发送 __schema 查询，拉取完整的类型、字段、参数、描述等元信息。
2. 用 graphql-js 的类型系统解析结果，区分对象、接口、联合和标量，而不是把所有类型当作同一种结构处理。
3. 解析 interface 与 union 的成员关系，让文档能说明某个类型实现了哪些接口、某个联合可能返回哪些具体类型。
4. 保留并输出自定义标量（custom scalar）的描述，避免文档里只剩一个 String/Int 之类的名字。

适用边界与注意点

• 依赖服务端开启内省。很多生产环境会关闭 __schema 查询，此时需要先用开发或预发环境的 endpoint。
• 文档质量受 schema 作者的注释习惯影响很大。没有写 description 的字段，输出里同样会缺少说明。
• 返回结果建议按项目或模块归档后再提交，否则大 schema 的文档很容易变成无人维护的单文件。
• 该技能基于 GraphQL.js，可用于 Node 服务中同时存在 require() 与 import 的场景，注意项目自身的模块规范。