【发布时间】：2017-01-23 02:50:36
【问题描述】：
借助 REST，我们可以使用 Swagger、RAML 或其他技术来记录我们的 API 并生成我们的消费者无需与服务器交互即可阅读的 HTML 文档。
GraphQL 是否存在类似的东西？有没有办法生成资源和属性的文档？
【问题讨论】：
标签： graphql graphql-js
【发布时间】：2017-01-23 02:50:36
【问题描述】：
据我所知，目前还没有工具可以自动为 GraphQL API 生成 HTML 文档，但我发现 GraphiQL 比我见过的任何 HTML 中的 API 文档更有用。
GraphiQL 让您可以交互式地探索 GraphQL 服务器的架构并同时针对它运行查询。它具有语法突出显示、自动完成功能，甚至可以在不执行查询的情况下告诉您查询何时无效。
如果您正在寻找静态文档，我发现阅读 GraphQL 模式语言中的模式非常方便。感谢 GraphQL 的另一个强大功能 - 模式自省 - 您可以轻松地为您可以访问的任何服务器打印模式。只需对服务器运行introspection query，然后像这样打印生成的内省模式（使用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
}
【讨论】：
-
谢谢，帮手。使用 API 作为文档的警告是，有时开发人员在访问之前需要它。例如：当决定购买一些 API 服务时。你提供了一个很好的替代这个警告。感谢您提供有用的答案。如果没有更好的来，我会稍等一下并将其标记为已接受。
现在好像有https://www.npmjs.com/package/graphql-docs
为 GraphQL 模式动态生成的文档浏览器。它旨在提供比 GraphiQL 更好的模式概览，但没有查询功能。
您还可以基于架构文件或 GraphQL 端点生成静态文档文件：
npm install -g graphql-docs
graphql-docs-gen http://GRAPHQL_ENDPOINT documentation.html
【讨论】：
-
这是否适用于使用 Spring Boot (Java) 开发的端点？
-
请注意，这自 2015 年以来一直没有更新（尽管我没有调查最近的分叉），并且它无法处理联合，因此可能无法解析您的架构。
【讨论】：
实际上 Graphql 使用 Facebook 的内置 Graphiql 或像 Altair 这样的第三方工具非常自我记录，因为查询/突变被列出并且返回类型也显示在那里。
我发现需要文档的一个地方是输入查询参数，它可能需要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]
}
如下所示：
图形：
牵牛星：
【讨论】：
如果您是 Sphinx / ReadTheDocs 用户，您可能会发现 https://github.com/hasura/sphinx-graphiql 很有用。
【讨论】：