如何使用 Swagger\OpenAPI 记录 GraphQL？

Posted 2023-02-19

【中文标题】如何使用 Swagger\\OpenAPI 记录 GraphQL？

【英文标题】：How to document GraphQL with Swagger \ OpenAPI?如何使用 Swagger\OpenAPI 记录 GraphQL？

【发布时间】：2020-12-29 06:08:53

【问题描述】：

如何使用 Swagger 记录 GraphQL？ 我们有一个庞大的后端 REST API，最近部分开始使用 GraphQL。我们使用 Swagger 来记录 API。

问题是：如何使用 Swagger(OpenAPI) 来记录 GraphQL 端点？ Swagger 或 GraphQL 的官方文档中绝对没有相关信息。

【问题讨论】：

相关（或重复）：Document a GraphQL API, Best approach to implement swagger in GraphQL application

这能回答你的问题吗？ Document a GraphQL API

【参考方案1】：

我只是有同样的要求。我基本上所做的是我将 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            "

【参考方案2】：

不幸的是，截至 2021 年 5 月，没有标准方法可以显示 GraphQL 端点或从 Swagger-UI 链接到 GraphiQL UI。

由于 GraphQL 正在与 REST 竞争，大多数 GraphQL 供应商希望开发人员将 REST 替换为 GraphQL，而不仅仅是将 GraphQL 用于（只读）查询。

希望，当 GraphQL 被更广泛地采用并更好地理解其优缺点时，更平衡的观点是使用两者中更好的部分。

【讨论】：

如果有一个统一的工具来支持这两个标准的文档，那就太好了

【参考方案3】：

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 查询，这对您的过渡期可能会很有趣。

【讨论】：

您似乎误解了这个问题。或者也许我不明白什么。生活中的一个简单例子：有一个前端开发人员，我用 GraphQL 为他做了一个后端。这个开发者如何理解如何使用这个 API？在 REST 的情况下，我可以将他发送到生成的 Swagger 页面，但我可以用 GraphQL 做什么？我应该告诉前端开发人员什么？我必须用语言告诉他吗？还是他必须通过后端代码才能了解它是如何工作的？请解释一下。

您将 URL 发送给他到您的 GraphQL API。所以假设它是https://my.api.com/graphql。现在他们可以使用他们的桌面应用程序“GraphQL Playground”（我已链接）简单地将这个 URL 放入其中并开始探索 API 文档。 GraphQL 是自我记录，这意味着通过构建服务器并将description 添加到字段中，GraphQL 客户端可以进行元查询，以获取有关 API 工作方式的所有信息。

您可以自己执行此操作并转到graphql.org/swapi-graphql 并单击右侧的“文档”链接。这只是开箱即用，完全免费。您还可以从您的服务器上提供此 graphiql 或 Playground。 Apollo Server 甚至内置了此功能，并将使用“Accept”标头text/html游乐场响应所有请求，而不是 API 响应。

GraphQL Playground 坏了：github.com/prisma-labs/graphql-playground/issues/877

我每天都将 Playground 用作 MacBook 上的应用程序，并通过浏览器提供服务。该问题似乎与 Playground 的问题无关，而是与用户相关问题的集合有关。但这并不能改变一个事实，即 GraphQL 不适用于 Swagger，您必须使用其他工具。

【参考方案4】：

OpenAPI-to-GraphQL 将 OpenAPI 规范 (OAS) 或 Swagger 描述的 API 翻译成 GraphQL。

Swagger-to-GraphQL 将您现有的 Swagger 模式转换为可执行的 GraphQL 模式，其中解析器对某些真实端点执行 HTTP 调用。它允许您以几乎零的努力将您的 API 迁移到 GraphQL，并同时维护 REST 和 GraphQL API。我们的 CLI 工具还允许您以模式定义语言获取 GraphQL 模式。

【讨论】：

这回答了一个不同的问题，即“如何使用 Swagger 文档在现有 REST API 之上构建 GraphQL API”。 OP 询问如何使用 Swagger 记录 GraphQL API。