使用dociql进行GraphQL文档生成

如果您使用GraphQL，您可能已经注意到维护文档是多么重要，尤其是当您的API有多个终端用户时。 在这种情况下，利用dociql工具来生成您的文档就成为了一个理想的选择。

介绍

dociql是一个用于生成GraphQL API文档的开源工具。它简化了文档生成的过程，并且可以允许用户能够自定义文档内容，旨在帮助团队快速了解GraphQL API的功能。

步骤

安装dociql

您可以通过以下命令在终端中安装dociql：

npm install -g dociql

配置环境变量

在生成文档之前，请确保在您的环境变量中设置了NODE_TLS_REJECT_UNAUTHORIZED标志。 如果您没有这样做，您将会收到TLS警告：`Error [ERR_TLS_CERT_ALTNAME_INVALID]: Hostname/IP does not match certificate's altnames: Host: localhost. Is not in the cert's altnames: DNS:.”

请使用以下命令运行dociql程序以安装环境变量：

NODE_TLS_REJECT_UNAUTHORIZED=0 dociql

使用

您可以使用以下命令来生成文档：

dociql <input> [options]

其中：

• <input>：GraphQL Schema文件的路径。
• options：生成文档时的选项。

例如，以下命令将生成您的GraphQL API的文档：

dociql ./schema.graphql

在该命令结束后，您可以在您的终端中看到以下输出：

Documentation generated successfully

使用自定义主题

默认主题将生成HTML格式的文档，而您可以通过使用自定义主题来生成Markdown格式的文档。以下是一个主题的示例：

module.exports = (docs, _config) => {
  const mdDocs = [];

  for (const type in docs.types) {
    if (type.charAt(0) === '_') continue;

    const typeName = `- ${type}\n`;
    mdDocs.push(typeName);

    const typeDesc = `**Description**: ${docs.types[type].description}\n\n`;

    mdDocs.push(typeDesc);

    if (docs.types[type].fields) {
      mdDocs.push('| Field | Type | Nullable | Description |\n');
      mdDocs.push('|-------|------|----------|-------------|\n');
      for (const field in docs.types[type].fields) {
        const fieldType = docs.types[type].fields[field].type.name;
        const nullable = `${docs.types[type].fields[field].nullable}`;
        const desc = docs.types[type].fields[field].description || '';

        mdDocs.push(`| ${field} | ${fieldType} | ${nullable} | ${desc} |\n`);
      }
      mdDocs.push('\n');
    } else {
      mdDocs.push(`\`${type}\` has no fields.\n`);
    }
  }

  return mdDocs.join('');
};

您可以在这个主题中进行自定义调整，以根据您的API适应自定义的Markdown格式。

要在该主题下生成文档，请在命令中添加--theme选项：

dociql ./schema.graphql --theme ./custom-theme.js

结论

dociql是一个很棒的工具，用于生成GraphQL文档。无需费时编写文档，您的团队可以更加关注API的开发和维护。