记录GraphQL API

Question

使用REST，我们可以使用Swagger、RAML或其他技术来记录我们的API，并生成一个HTML文档，我们的消费者可以阅读该文档，而无需与服务器进行任何交互。

GraphQL是否存在类似的情况？是否有任何方法生成资源和属性的文档？

Answer 1

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

HTML 导出如下所示。

GitHub GraphQL文档示例

Answer 2

据我所知，目前还没有工具可以为 GraphQL API 自动生成 HTML 文档，但我发现 GraphiQL 比我见过的任何 HTML API 文档都更有用。

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

如果您正在寻找静态文档，我发现用GraphQL模式语言阅读模式非常方便。由于GraphQL的另一个强大功能-模式内省-您可以轻松地为您有权访问的任何服务器打印模式。只需对服务器运行内省查询，然后像这样打印生成的内省模式（使用graphqljs）：

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

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

为GraphQL架构动态生成的留档资源管理器。它旨在提供比GraphiQL更好的架构概述，但没有查询功能。

您还可以基于架构文件或GraphQLendpoint生成静态留档文件：

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