如何使用 Swagger \ OpenAPI 记录 GraphQL？

Question

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

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

Answer 1

GraphQL API 通常通过 GraphQL 服务器本身提供的文档工具来记录：类型系统以及类型和字段的描述。像GraphQL playground这样的工具可以让您通过在可视化文档树中单击/搜索或通过类似 IDE 的功能（自动完成 + 工具提示）来探索 API 文档。这主要是公司公开其公共 GraphQL API 的方式。一些公司还公开了 swagger 之类的文档（例如Github v4 API 文档）。此工具可以为您的 API 创建这样的文档。

另一方面，Swagger 为 REST API 解决了这个问题。因此，Swagger 是为不同的生态系统构建的。Swagger 向 REST 添加了在 GraphQL 中开箱即用的功能。因此，据我所知，任何一方都没有尝试创建兼容性。有一些工具可以将 Swagger/OpenAPI REST 端点公开为 GraphQL 查询，这在您的过渡期可能会很有趣。

Answer 2

我只是有同样的要求。我基本上所做的是将 GraphQL 描述为一个 REST API - 基本上它是：它是一个 HTTP 端点，它使用 POST 方法，它在正文中发布 json 数据并接收 json 作为答案。

我发现不可能以 swagger 的方式记录所有查询，但有可能达到这样的程度，以便它可用。

这是我创建的 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 {
  searchProducts(term: "MySearchTerm", language: EN) {
    hits {
      source {
        id
        Name
        Number
      }
    }
  }
}

Answer 3

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

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

希望当 GraphQL 得到更广泛的采用并且更好地理解它的优点和缺点时，一个更平衡的观点将是使用两者中更好的部分。