随着 Web 应用程序越来越复杂和强大，前端开发人员需要一种更好的方法来管理和组织应用程序的数据。GraphQL 是一种流行的解决方案，它使前端开发人员能够定义和获取自己需要的数据。 然而，尽管 GraphQL 是一种灵活且强大的解决方案，但实际应用在中大型企业级 Web 应用程序时还是存在一些挑战。
OpenAPI 是一种用于定义 RESTful API 的编程语言和工具集，可以描述每个请求和响应的属性和操作。 将 OpenAPI 与 GraphQL 结合使用，可以提供更好的类型安全性、更好的文档性能和更好的函数绑定。这篇文章将介绍如何在 GraphQL 中使用 OpenAPI，并提供示例代码和指导。
OpenAPI
OpenAPI 的核心是 JSON 文件格式，用于描述 RESTful API。该文件叫做 OpenAPI 规范（以前称为 Swagger 规范）。 此规范有几个版本，我们将使用版本 3。
例如，以下是一个简单的 OpenAPI 规范：
-- -------------------- ---- -------
-------- -----
-----
------ ------ ---
-------- -----
------
-------
----
-------- --- - ---- -- -----
-----------
- --- -----
----- -----
-------
----- -------
-------- -
-------- ---
------------ --- ------- ------ -- ----- -- -------
----------
----
------------ --在这个规范中，我们定义了一个名为 "/users" 的 API 路径，该路径对应一个 RESTful API 的 GET 方法。 我们指定了一个查询参数“limit”，它在请求中接受一个整数参数，并提供了一个介于 1 到 100 之间的最小值和最大值。 该 API 的响应是一个 HTTP 200 OK 状态码。这个规范提供了一种清晰和可扩展的方法来定义 RESTful API。
GraphQL 中的 OpenAPI
GraphQL 是一种更加灵活的解决方案，图形化地描述了前端数据，它放弃了 RESTful API 的强制结构，但它也引入了一些困难。
GraphQL 提供了一个 Schema 和 Resolver 的解决方案，用于定义和展示前端数据类型。但是，当与 RESTful API 或其他后端服务交互时，前端开发人员可能会遇到以下问题：
- 需要正确的类型安全性
- 需要正确的文档性能
- 需要正确的函数绑定
这些问题可以通过将 OpenAPI 与 GraphQL 集成来解决。
将 OpenAPI 转换为 GraphQL Schema
要在 GraphQL 中使用 OpenAPI，我们需要将 OpenAPI 规范转换为 GraphQL Schema。这个过程可以采用一个 JavaScript 库，叫做 OpenAPI-to-GraphQL，它实现了这个转换过程。
以下是将上面的 OpenAPI 规范转换为 GraphQL Schema 的示例代码：
-- -------------------- ---- -------
----- ------- - -------------------
----- - ----------- - - ---------------------------
----- ---------------- - ------------------------------
----- -------- ------- -
----- - ------ - - ----- ---------------------------------------------------------------
----- --- - ----------
--------
-----------
-------------
-------
--------- -----
--
--
-----------------
-
--------在这个示例中，我们使用 openapi-to-graphql 库将“simple.yaml”规范转换为 GraphQL Schema，并将其附加到了使用 Express.js 实现的 GraphQL 服务中。这将允许我们使用自动生成的类型来查询 /users API。
使用 OpenAPI 和 GraphQL 查询数据
一旦我们将 OpenAPI 转换为 GraphQL Schema，我们就可以在 GraphQL 中轻松地使用它们了。 下面是一个示例查询，该查询使用上面的示例 API 获取用户名单并返回前三个用户：
query {
users(limit: 3) {
name
email
phone
}
}上述查询中使用了 "/users" API 的查询参数“limit”，它允许我们从服务器获取的用户数量进行限制。 返回的数据将是 GraphQL 自动为我们生成的类型，这些类型基于我们在 OpenAPI 规范中定义的数据模型。
我们还可以使用 GraphQL 变异来更新后端数据。 以下是一个示例变异，在联系人列表中添加新联系人：
mutation {
addContact(name: "John Doe", email: "john.doe@example.com", phone: "5551234567") {
id
name
email
phone
}
}该变异将使用我们在 OpenAPI 规范中定义的数据模型定义的内容将新联系人添加到我们的联系人列表中。
结论
使用 OpenAPI 来扩展 GraphQL 可以为前端开发人员带来很多好处。它提供了更好的类型安全性、更好的文档性能和更好的函数绑定。OpenAPI 规范为我们提供了一种基于规范的 RESTful API 描述形式，我们可以为它编写任意数量的 GraphQL 查询和变异。这使得我们在管理和组织 Web 应用程序的数据时变得更加灵活和容易，进而增加了开发人员的开发效率并降低了代码的复杂性。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/672f1622eedcc8a97c8c79a8