记录 GraphQL API

使用 REST，我们可以使用 Swagger、 RAML 或其他技术来记录我们的 API 并生成 HTML 文档，我们的用户可以阅读这些文档，而不需要与服务器进行任何交互。

GraphQL 是否存在类似的东西? 是否有任何方法来生成资源和属性的文档？

46968 次浏览
小开

据我所知，目前还没有一种工具可以为 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
}
小开
最佳答案

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

动态生成的 GraphQL 模式文档浏览器。它旨在提供比 GraphiQL 更好的模式概述，但是没有查询特性。

enter image description here

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

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

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

HTML 导出如下所示。

GitHub GraphQL doc 示例

小开

实际上，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

牵牛星:

Altair

小开

如果您是 Sphinx/ReadTheDocs 用户，您可能会发现 https://github.com/hasura/sphinx-graphiql很有用。

小开

另一个最近的工具是 SpectaQL。输出可以看起来像 这个。 引用自述:

自动生成静态 GraphQLAPI 文档。

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

  1. 使用内省查询从活动端点。
  2. 从包含自省查询结果的文件。
  3. 来自导致 SDL 中的模式定义的文件、文件或 Globb。

SpectaQL 的目标是帮助您保持文档的完整性, 现代的，美丽的，尽可能少的痛苦。

开箱即用，SpectaQL 提供了一个具有现代外观的3栏页面 然而，许多方面可以轻松定制，而且公正 只要你愿意，任何东西都可以定制。

小开

现在还有 Magdoc，这是一个新工具，可以使用自省查询或 sdl 文件为任何 API 生成静态 GraphQL 文档网站。

这是 GitHub 存储库，文件可在 https://magidoc.js.org获得

小开

可以添加到列表中: https://github.com/anvilco/spectaql

SpectaQL 是一个 Node.js 库，它为 GraphQL 模式生成静态文档


提交答案