# @2fd/graphdoc 中文文档 规范地址：https://npmcn.com/package/%402fd/graphdoc/ 版本：2\.4\.0 npm 元数据更新时间：2022-06-12T14:10:32.227Z 中文译文更新时间：2026-11-05T19:41:26.331Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%402fd/graphdoc 原文对照：https://npmcn.com/package/%402fd/graphdoc/?lang=original 项目主页：https://github.com/2fd/graphdoc#readme 源码仓库：https://github.com/2fd/graphdoc ## 关键信息（来自 npm 元数据） - 模块格式：CommonJS - TypeScript 类型：未声明 - 运行依赖：11 个 - 首次发布：2016-08-29T07:28:23.137Z - 最新版本发布：2017-08-02T04:23:43.122Z - 近 30 天下载量：33450（2026-10-05 至 2026-11-03，npm 官方下载统计） - 已发布版本数：12（近 12 个月 0 个） ## 中文简介 用于记录 GraphQL Schema 的静态页面生成器 ## 安装 ```sh npm install @2fd/graphdoc ``` 也可以使用：`pnpm add @2fd/graphdoc`、`yarn add @2fd/graphdoc`、`bun add @2fd/graphdoc` ## README # 用于记录 GraphQL Schema 的静态页面生成器 [![Build Status](https://travis-ci.org/2fd/graphdoc.svg?branch=master)](https://travis-ci.org/2fd/graphdoc) ![npm (scoped)](https://img.shields.io/npm/v/@2fd/graphdoc.svg?style=flat-square) ![GitHub tag](https://img.shields.io/github/tag/2fd/graphdoc.svg?style=flat-square) ## 演示文稿 - Facebook 测试 [星球大战](https://2fd.github.io/graphdoc/star-wars) - [Github 图形QL](https://2fd.github.io/graphdoc/github) - [Pokemon 图形QL](https://2fd.github.io/graphdoc/pokemon) ## 安装 ```bash npm install -g @2fd/graphdoc ``` ## 使用 ### 从活端生成文档 ```bash > graphdoc -e http://localhost:8080/graphql -o ./doc/schema ``` ### 从 IDL 文件生成文档 ```bash > graphdoc -s ./schema.graphql -o ./doc/schema ``` ### 生成文档 ["模式化计划"](http://dev.apollodata.com/tools/graphql-tools/generate-schema.html#modularizing) 图表ql工具 ```bash > graphdoc -s ./schema.js -o ./doc/schema ``` > [`./schema.graphql`](https://github.com/2fd/graphdoc/blob/master/test/starwars.graphql) 必须能够用 [图ql-js/用途#建设计划](http://graphql.org/graphql-js/utilities/#buildschema) ### 从 json 文件生成文档 ```bash > graphdoc -s ./schema.json -o ./doc/schema ``` > `./schema.json` 包含 [图QL 内向查询](https://github.com/2fd/graphdoc/blob/gh-pages/introspection.graphql) ### 将选项放入 `package.json` ```javascript // package.json { "name": "project", // [...] "graphdoc": { "endpoint": "http://localhost:8080/graphql", "output": "./doc/schema", } } ``` 执行 ```bash > graphdoc ``` ### 帮助 ```bash > graphdoc -h Static page generator for documenting GraphQL Schema v1.2.0 Usage: graphdoc [OPTIONS] [OPTIONS]: -c, --config Configuration file [./package.json]. -e, --endpoint Graphql http endpoint ["https://domain.com/graphql"]. -x, --header HTTP header for request (use with --endpoint). ["Authorization: Token cb8795e7"]. -q, --query HTTP querystring for request (use with --endpoint) ["token=cb8795e7"]. -s, --schema Graphql Schema file ["./schema.json"]. -p, --plugin Use plugins [default=graphdoc/plugins/default]. -t, --template Use template [default=graphdoc/template/slds]. -o, --output Output directory. -b, --base-url Base url for templates. -f, --force Delete outputDirectory if exists. -v, --verbose Output more information. -V, --version Show graphdoc version. -h, --help Print this help ``` ## 插件 在图文件中,插件只是控制显示内容的对象 在文档的每一页. 此对象只应执行 `PluginInterface`。 。 。 . ```typescript /** * PluginInterface */ export interface PluginInterface { /** * Return section elements that is going to be * inserted into the side navigation bar. * * @example plain javascript: * [ * { * title: 'Schema', * items: [ * { * text: 'Query', * href: './query.doc.html', * isActive: false * }, * // ... * } * // ... * ] * * @example with graphdoc utilities: * import { NavigationSection, NavigationItem } from 'graphdoc/lib/utility'; * * [ * new NavigationSection('Schema', [ * new NavigationItem('Query', ./query.doc.html', false) * ]), * // ... * ] * * @param {string} [buildForType] - * the name of the element for which the navigation section is being generated, * if it is `undefined it means that the index of documentation is being generated */ getNavigations?: (buildForType?: string) => NavigationSectionInterface[] | PromiseLike; /** * Return section elements that is going to be * inserted into the main section. * * @example plain javascript: * [ * { * title: 'GraphQL Schema definition', * description: 'HTML' * }, * // ... * ] * * @example with graphdoc utilities: * import { DocumentSection } from 'graphdoc/lib/utility'; * * [ * new DocumentSection('GraphQL Schema definition', 'HTML'), * // ... * ] * * @param {string} [buildForType] - * the name of the element for which the navigation section is being generated, * if it is `undefined it means that the index of documentation is being generated * */ getDocuments?: (buildForType?: string) => DocumentSectionInterface[] | PromiseLike; /** * Return a list of html tags that is going to be * inserted into the head tag of each page. * * @example * [ * '', * '', * ] */ getHeaders?: (buildForType?: string) => string[] | PromiseLike; /** * Return a list of abasolute path to files that is going to be * copied to the assets directory. * * Unlike the previous methods that are executed each time that a page generated, * this method is called a single time before starting to generate the documentation * * @example * [ * '/local/path/to/my-custom-style.css', * '/local/path/to/my-custom-image.png', * ] * * there's will be copied to * /local/path/to/my-custom-style.css -> [OUTPUT_DIRETORY]/assets/my-custom-style.css * /local/path/to/my-custom-image.png -> [OUTPUT_DIRETORY]/assets/my-custom-image.png * * If you want to insert styles or scripts to the documentation, * you must combine this method with getHeaders * * @example * getAssets(): ['/local/path/to/my-custom-style.css'] * getHeaders(): [''] */ getAssets?: () => string[] | PromiseLike; } ``` ### 制作一个插件 要创建自己的插件, 您只应该创建为 `plain object` 或一个 `constructor` 并导出为 `default` 如果您将插件导出为构造器, 当您要初始化时, 将获得三个参数 - `schema`: 全部结果 [图QL 内向查询](https://github.com/2fd/graphdoc/blob/gh-pages/introspection.graphql) - `projectPackage`页:1 `package.json` 当前项目(或定义为 `--config` 旗帜). - `graphdocPackag`页:1 `package.json` 图表文件. > 出于性能原因,所有插件都收到同一对象的引用 因此,不应该直接修改它们,因为它可能影响行为 其他插件(当然除非您的意图) #### 实例 ```typescript // es2015 export constructor export default class MyPlugin { constructor(schema, projectPackage, graphdocPackag){} getAssets() { /* ... */ } /* ... */ } ``` ```typescript // es2015 export plain object export default cost myPlugin = { getAssets() { /* ... */ }, /* ... */ } ``` ```javascript // export constructor function MyPlugin(schema, projectPackage, graphdocPackage) { /* ... */ } MyPlugin.prototype.getAssets = function() { /* ... */ }; /* ... */ exports.default = MyPlugin; ``` ```javascript // export plain object exports.default = { getAssets: function() { /* ... */ }, /* ... */ } ``` ### 使用插件 您可以以两种方式使用插件 . #### 使用带有命令行的插件 ```bash > graphdoc -p graphdoc/plugins/default \ -p some-dependencie/plugin \ -p ./lib/plugin/my-own-plugin \ -s ./schema.json -o ./doc/schema ``` #### 使用插件为 `package.json` ```javascript // package.json { "name": "project", // [...] "graphdoc": { "endpoint": "http://localhost:8080/graphql", "output": "./doc/schema", "plugins": [ "graphdoc/plugins/default", "some-dependencie/plugin", "./lib/plugin/my-own-plugin" ] } } ``` ### 内建插件 > 开始 ## 模板 > 开始 ## 常见问题 ### @2fd/graphdoc 是什么？ 用于记录 GraphQL Schema 的静态页面生成器 ### 如何安装 @2fd/graphdoc？ 在项目目录运行 npm install @2fd/graphdoc，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 graphdoc，可以用 npx graphdoc 直接运行。 ### @2fd/graphdoc 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/2fd\_\_graphdoc 是否存在。 ### @2fd/graphdoc 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @2fd/graphdoc 可以商用吗？ @2fd/graphdoc 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @2fd/graphdoc 的下载量有多少？ 根据 npm 官方下载统计，@2fd/graphdoc 在 2026/10/05 – 2026/11/03 这 30 天内被下载 33,450 次，日均约 1,115 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @2fd/graphdoc 还在维护吗？ 最新版本 2\.4\.0 发布于 2017/08/02（9 年前）；至今共发布 12 个版本，其中过去 12 个月发布了 0 个；首次发布于 2016/08/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。