如何使用 Swagger 记录 GraphQL？ 我们有一个庞大的后端 REST API，最近部分开始使用 GraphQL。我们使用 Swagger 来记录 API。
问题是：如何使用 Swagger(OpenAPI) 来记录 GraphQL 端点？ Swagger 或 GraphQL 的官方文档中绝对没有相关信息。
【问题讨论】：
标签： rest graphql swagger documentation openapi
我只是有同样的要求。我基本上所做的是我将 GraphQL 描述为好像它是一个 REST API - 基本上它是：它是一个 HTTP 端点，它使用 POST 方法，它在正文中发布 json 数据并接收 json 作为答案。
我发现不可能用 swagger 记录所有查询，但有可能达到这样的程度，以便它可以使用。
这是我创建的招摇 yaml：
swagger: "2.0"
info:
description: "Graphql swagger"
version: "1.0.0"
title: "Graphql swagger"
host: "my-graphql-host.com"
basePath: "/"
schemes:
- "https"
paths:
/api:
post:
summary: "GraphQL"
consumes:
- "application/json"
produces:
- "application/json"
responses:
"200":
description: "successful operation"
schema:
$ref: "#/definitions/GraphQLResponse"
parameters:
- in: body
name: body
description: "GraphQL query"
required: true
schema:
$ref: "#/definitions/GraphQLQuery"
definitions:
GraphQLQuery:
type: "object"
properties:
query:
type: "string"
GraphQLResponse:
type: "object"
properties:
data:
type: "object"
这是这个 swagger 文档预览的样子：
如您所见，它只描述了一个查询被接受，但没有描述哪些查询。
因此，要执行查询，您需要将其转换为字符串并将其传递给正文。这意味着，以下查询：
query {
searchProducts(term: "MySearchTerm", language: EN) {
hits {
source {
id
Name
Number
}
}
}
}
需要转化为
{
"query": "query { searchProducts(term: \"MySearchTerm\", language: EN) { hits { source { id Name Number } } }}"
}
【讨论】：
不幸的是，截至 2021 年 5 月，没有标准方法可以显示 GraphQL 端点或从 Swagger-UI 链接到 GraphiQL UI。
由于 GraphQL 正在与 REST 竞争，大多数 GraphQL 供应商希望开发人员将 REST 替换为 GraphQL，而不仅仅是将 GraphQL 用于（只读）查询。
希望，当 GraphQL 被更广泛地采用并更好地理解其优缺点时，更平衡的观点是使用两者中更好的部分。
【讨论】：
GraphQL API 通常通过 GraphQL 服务器本身提供的文档工具进行记录：类型系统以及类型和字段的描述。 GraphQL playground 之类的工具可让您通过在可视文档树中单击/搜索或通过类似 IDE 的功能（自动完成 + 工具提示）来探索 API 文档。这主要是公司公开其公共 GraphQL API 的方式。一些公司还公开了类似文档的招摇（例如Github v4 API docs）。 This tool 可以为您的 API 创建这样的文档。
另一方面，Swagger 为 REST API 解决了这个问题。因此，Swagger 是为不同的生态系统而构建的。 Swagger 为 REST 添加了在 GraphQL 中开箱即用的功能。据我所知，双方都没有尝试创建兼容性。有一些工具可以将 Swagger/OpenAPI REST 端点公开为 GraphQL 查询，这对您的过渡期可能会很有趣。
【讨论】：
https://my.api.com/graphql。现在他们可以使用他们的桌面应用程序“GraphQL Playground”（我已链接）简单地将这个 URL 放入其中并开始探索 API 文档。 GraphQL 是自我记录，这意味着通过构建服务器并将description 添加到字段中，GraphQL 客户端可以进行元查询，以获取有关 API 工作方式的所有信息。
text/html游乐场响应所有请求，而不是 API 响应。
OpenAPI-to-GraphQL 将 OpenAPI 规范 (OAS) 或 Swagger 描述的 API 翻译成 GraphQL。
Swagger-to-GraphQL 将您现有的 Swagger 模式转换为可执行的 GraphQL 模式，其中解析器对某些真实端点执行 HTTP 调用。它允许您以几乎零的努力将您的 API 迁移到 GraphQL，并同时维护 REST 和 GraphQL API。我们的 CLI 工具还允许您以模式定义语言获取 GraphQL 模式。
【讨论】：