让工具读懂两种接口语言：GraphQL 与 OpenAPI 自动生成文档的落地难点
GraphQL 与 REST API 文档统一的根本挑战在于两种接口哲学差异：OpenAPI 是资源视图，GraphQL 是能力视图。强行用同一种生成逻辑会导致文档残缺。可行的统一路径包括以 GraphQL 为主封装 REST、用 OpenAPI 扩展承载 GraphQL 语义，或双 schema 并存通过中间层做字段映射统一渲染。落地时需注意工具选型、参数展示区分、统一错误格式，并做好手动维护映射与示例的准备。