记录GraphQL API

Question

使用REST,我们可以使用Swagger,RAML或其他技术来记录我们的API并生成HTML文档,我们的消费者可以在不需要与服务器交互的情况下阅读这些文档.

为GraphQL做一些类似的事情吗？有没有办法生成资源和属性的文档？

Answer 1

看起来现在有https://www.npmjs.com/package/graphql-docs

动态生成的GraphQL架构文档资源管理器.它旨在提供比GraphiQL更好的模式概述,但不需要查询功能.

您还可以基于模式文件或GraphQL端点生成静态文档文件:

npm install -g graphql-docs
graphql-docs-gen http://GRAPHQL_ENDPOINT documentation.html

Answer 2

据我所知,还没有为GraphQL API自动生成HTML文档的工具,但我发现GraphiQL比我见过的HTML中的任何API文档都更有用.

GraphiQL允许您以交互方式探索GraphQL服务器的模式,并同时对其运行查询.它具有语法高亮,自动完成功能,甚至可以在不执行查询的情况下告诉您查询何时无效.

如果您正在寻找静态文档,我发现用GraphQL模式语言读取模式非常方便.由于GraphQL的另一个重要功能 - 模式内省 - 您可以轻松地为您有权访问的任何服务器打印模式.只需对服务器运行内省查询,然后像这样打印生成的内省模式(使用graphql-js):

var graphql = require('graphql');
var introspectionSchema = {}; // paste schema here
console.log(graphql.printSchema(graphql.buildClientSchema(introspectionSchema)));

结果将如下所示:

# An author
type Author {
  id: ID!

  # First and last name of the author
  name: String
}

# The schema's root query type
type Query {

  # Find an author by name (must match exactly)
  author(name: String!): Author
}

Answer 3

我找到了用于记录GraphQL Schema的静态页面生成器.GitHub链接.

HTML导出看起来像这样.

GitHub GraphQL doc示例

Answer 4

实际上，Graphql完全是用Facebook的内置Graphiql工具或第三方工具自记录的，例如Altair因为列出了查询/突变，并且在那里还显示了返回类型，所以它很容易记录。

我发现需要doc的地方之一可能是需要的输入查询参数specific format。这可以通过在这些注释的顶部添加注释来实现arguments。

  type Query {
      eventSearch(
        # comma separated location IDs. (eg: '5,12,27')
        locationIds: String,
        # Date Time should be ISO 8601: 'YYYY-DD-MM HH:mm:ss'. (eg: '2018-04-23 00:00:00')
        startDateTime: String!,
        endDateTime: String!): [Event]
  }

它将如下所示：

Graphiql：

牵牛星：

Answer 5

另一个最近的工具是SpectaQL。输出可能如下所示。引用自述文件：

自动生成静态 GraphQL API 文档。

SpectaQL 是一个 Node.js 库，它使用各种选项为 GraphQL 模式生成静态文档：

1. 使用内省查询从实时端点。
2. 来自包含内省查询结果的文件。
3. 从一个、多个文件或 glob 通向 SDL 中的模式定义。

SpectaQL 的目标是帮助您以尽可能少的痛苦保持文档的完整性、最新性和美观性。

SpectaQL 开箱即用，提供具有现代外观和感觉的 3 列页面。然而，许多方面都可以轻松定制，而且如果您愿意深入研究，几乎所有内容都可以定制。