推荐使用：GraphQL文档生成器 - gqldoc

gqldoc 是一款强大的命令行工具，用于从GraphQL模式或你的GraphQL端点自动生成文档。这个命令是使用Go 1.16及以上版本编写的，所以如果你想要构建它，你需要确保你的Go环境版本符合要求。

项目演示

查看以下示例，以了解gqldoc的出色效果：

• Star Wars API 演示：example/starwars
• Git平台 V4 API 演示：example/gitplatform ，公共模式可在此查阅：Git平台官方文档

如何使用

使用gqldoc既简单又灵活，你可以通过以下两种方式生成文档：

1. 从GraphQL端点生成

   确保开启GraphQL的Introspection功能，并提供必要的请求头（如认证令牌）：

   $ gqldoc -e http://127.0.0.1:8081/query --header 'Authorization: Bearer token' -o ./doc_dir
   

2. 从GraphQL模式文件生成

   支持.json，.graphql和.gql扩展名。对于.json文件，需包含Introspection的结果：

   $ gqldoc -s schema.graphql -o ./doc_dir
   

   使用--schema标志可以多次指定多个模式文件，甚至可以用glob模式匹配：

   $ gqldoc -s "schema/**/*.graphql" -o ./doc_dir
   

安装

对Mac和Linux用户，可以通过Homebrew轻松安装：

$ brew install Code-Hex/tap/gqldoc

其他用户可以通过go命令手动安装（需要Go 1.16+环境）：

$ go install github.com/Code-Hex/gqldoc/cmd/gqldoc@latest

或者，直接从release页面下载对应操作系统的二进制文件。

未来规划

gqldoc仍然在不断进步中，以下是开发团队的优先事项：

• [x] 已实现：支持Git平台Actions集成（提供了更新文档并推送至当前分支的功能）
• [ ] 订阅功能
• [ ] 添加对Directive及其位置的支持
• [x] 实现：在输出目录中创建README.md（用于生成目录）
• [ ] 自定义模板
• [ ] 渲染HTML页面（目前还在考虑是否要加入此特性）

看到这里，你可能会对gqldoc的强大功能印象深刻。无论你是需要为API编写清晰的文档，还是希望简化工作流程，gqldoc都是一个值得信赖的选择。立即试一试，让gqldoc帮助你提升工作效率，打造高质量的GraphQL文档吧！