如何使用Swagger/OpenAPI记录GraphQL？

Question

如何使用Swagger记录GraphQL?

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

问题在于：如何使用Swagger（OpenAPI）记录GraphQL终端点？Swagger或GraphQL的官方文档中完全没有相关信息。

- user12367662

---

相关（或重复）：文档化GraphQL API，在GraphQL应用程序中实现Swagger的最佳方法。 - Helen

这个回答解决了你的问题吗？记录一个GraphQL API - Antares42

Answer 1

GraphQL API通常通过GraphQL服务器本身提供的文档设施进行文档化，包括类型系统和类型和字段的描述。像GraphQL playground这样的工具允许您通过在可视化文档树中单击/搜索或通过IDE功能（自动完成+工具提示）来探索API文档。这主要是公司公开其GraphQL API的方式。一些公司还公开Swagger类似的文档（例如GitHub v4 API docs）。这个工具可以为您的API创建这种文档。

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

- Herku

---

你似乎误解了问题。或者我没有理解清楚。生活中的一个简单例子：有一个前端开发人员，我为他制作了一个GraphQL后端。这个开发人员如何理解如何使用这个API呢？ 在REST的情况下，我可以直接将他发送到生成的Swagger页面，但是在GraphQL中我该怎么办呢？我应该告诉前端开发人员什么？我需要用语言告诉他吗？还是他必须通过后端代码来理解它的工作原理？请解释一下。 - user12367662

你可以将你的GraphQL API链接发送给他。比如说它是https://my.api.com/graphql。现在他们可以使用我提供的桌面应用程序"GraphQL Playground"，把这个链接放进去，开始探索API文档。GraphQL是自我说明的，这意味着通过构建服务器并向字段添加"description"，一个GraphQL客户端可以发起元查询，获取有关API工作方式的所有信息。 - Herku

你可以自己操作，前往 https://graphql.org/swapi-graphql 并点击右侧的“docs”链接。这个功能是开箱即用的，完全免费。你也可以从你的服务器上提供这个 GraphiQL 或 Playground。Apollo Server 甚至已经内置了这个功能，并将以“text/html”为“Accept”头响应所有请求，而不是 API 响应，以展示 Playground。 - Herku

GraphQL Playground出现故障：https://github.com/prisma-labs/graphql-playground/issues/877 - user12367662

有一个游乐场可用。https://www.apollographql.com/docs/apollo-server/v2/testing/graphql-playground/ - tufac2

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": "query {  searchProducts(term: \"MySearchTerm\", language: EN) {    hits {      source {        id        Name        Number      }    }  }}"
}

- Thomas Sparber

Answer 3

很遗憾，截至2021年5月，目前没有标准的方式能够在Swagger-UI中展示GraphQL端点或链接到GraphiQL UI。

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

希望随着GraphQL被更广泛地采用，并且人们对它的优缺点有了更好的认识，从两者中使用更好的部分会得到更加平衡的视角。

- Paul Verest

---

如果有一个统一的工具来支持两种标准的文档编写，那将是非常好的。 - Rigin Oommen

Answer 4

OpenAPI-to-GraphQL是一个将OpenAPI规范（OAS）或Swagger描述的API转换为GraphQL的工具。

OpenAPI-to-GraphQL有两种使用方式：

命令行界面（CLI）

命令行界面（CLI）提供了一种方便的方式来启动一个GraphQL服务器，包装给定OpenAPI规范的API：

使用以下命令安装OpenAPI-to-GraphQL CLI：

npm i -g openapi-to-graphql-cli

然后，运行OpenAPI-to-GraphQL命令并指向一个OpenAPI规范：

openapi-to-graphql [options]

更多详细信息，请参考openapi-to-graphql-cli文档。

库

在应用程序中使用OpenAPI-to-GraphQL作为库，生成GraphQL模式。

安装OpenAPI-to-GraphQL作为依赖项:

npm i -s openapi-to-graphql

Require OpenAPI-to-GraphQL and use the createGraphQLSchema function:
const { createGraphQLSchema } = require("openapi-to-graphql");
// load or construct OAS (const oas = ...)
const { schema, report } = await createGraphQLSchema(oas);

更多详细信息，请参考openapi-to-graphql-cli文档。

- Tomer Bar-Shlomo

---

问题是相反的 ‍♂️ - Fyodor