在前端开发中，文档是非常重要的一部分。对于 GraphQL 接口的文档，@2fd/graphdoc 是非常有用的工具。它可以根据 GraphQL schema 自动生成静态网页文档。
安装和使用
通过 npm 安装 @2fd/graphdoc，然后直接在终端中运行。
npm i -g @2fd/graphdoc graphdoc -e http://localhost:4000/graphql -o ./docs
其中 -e 是 GraphQL endpoint，-o 是生成文档的目录。
运行成功后可以访问生成的文档：
http://localhost:8080/docs
配置选项
@2fd/graphdoc 社区支持多种配置选项，常见的包括：
定制模板
@2fd/graphdoc 支持多种模板，可以通过 -t 参数指定模板。
graphdoc -e http://localhost:4000/graphql -o ./docs -t /path/to/template
需要注意，模板目录必须包含 index.html 文件。
配置标题和描述
我们还可以通过配置 title 和 description 参数来指定文档的标题和描述。
graphdoc -e http://localhost:4000/graphql -o ./docs -t /path/to/template --title "GraphQL API" --description "API documentation"
配置样式
@2fd/graphdoc 的样式默认是比较简单的，但是我们可以通过自定义 CSS 来美化界面。
graphdoc -e http://localhost:4000/graphql -o ./docs -t /path/to/template -s /path/to/styles.css
配置语言
@2fd/graphdoc 支持多国语言，我们可以通过配置语言来生成对应文档。
graphdoc -e http://localhost:4000/graphql -o ./docs -t /path/to/template --language zh-cn
目前支持的语言有：
- 简体中文：zh-cn
- 繁体中文：zh-tw
- 英文：en
高级用法
如果我们需要自定义文档内容，可以使用自定义模板。模板可以实现更加复杂的功能，例如：
自动生成导航栏
自定义模板可以通过 JavaScript 生成 HTML，从而实现根据 schema 自动生成导航栏的功能。
<div class="navigation">
{{#each objectTypes}}
<div class="entry">
<a href="#{{name}}">{{name}}</a>
</div>
{{/each}}
</div>根据类型生成不同颜色的标签
如果我们需要为不同种类的类型生成不同的颜色标签，可以通过自定义模板实现。
<span class="doc-tag {{ type.category }}">{{ type.name }}</span>其中，type.category 表示类型的种类。例如，Scalar、Object、Enum 等。可以通过 CSS 预定义每种种类对应的颜色。
-- -------------------- ---- ------- --------------- - ----------------- -------- - --------------- - ----------------- -------- - ------------- - ----------------- -------- -
最终生成的效果如下图：
使用建议
@2fd/graphdoc 是一个非常优秀的 GraphQL 文档生成器，但是在使用中还是有一些需注意的细节：
- 不要将文档文件直接放在项目根目录，最好使用子目录存放；
- 建议将文档文件一并提交到代码仓库中，方便协作和更新；
- 建议编写合适的脚本，方便自动化生成和推送；
总之，@2fd/graphdoc 可以帮助我们生成漂亮的 GraphQL 文档，提高项目的可读性和易用性。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/103105