前言
随着微服务的流行，越来越多的公司选择使用 OpenAPI 3.0 标准来描述 API 接口。但是，对于前端工程师来说，如何在开发中使用 OpenAPI 3.0 规范的文档就成了一个难题。而 npm 包 openapi3-util 的出现，则使这个问题得以解决。本文将为大家介绍如何使用该 npm 包。
了解 OpenAPI 3.0 规范
在使用 openapi3-util 之前，我们需要先了解 OpenAPI 3.0 规范。
OpenAPI 3.0 是一种标准，它通过 YAML 或 JSON 字符串的形式描述 RESTful API 的接口。OpenAPI 是 Web API 开发的一种规范集合，它定义了如何描述 API 的接口，包括请求参数、响应体、错误码等信息。除此之外，OpenAPI 还支持许多其他功能，例如描述安全、描述联合 API 等。
安装 openapi3-util
在使用 openapi3-util 之前，需要先安装它。可以使用 npm 进行安装，命令如下：
npm install openapi3-util
安装完毕之后，即可在项目中使用该包。
使用 openapi3-util
使用 openapi3-util 的方法非常简单，主要分为两个阶段，即将 OpenAPI 规范转换为 JSON Schema，以及根据 JSON Schema 生成前端代码。
将 OpenAPI 规范转换为 JSON Schema
使用 openapi3-util 将 OpenAPI 规范转换为 JSON Schema 的方法非常简单，只需要调用该包提供的 convert 函数，并将 OpenAPI 规范作为参数传递进去即可。例如：
const openapi3Util = require('openapi3-util');
const schema = openapi3Util.convert(openapiDocument);其中，openapiDocument 为 OpenAPI 规范的文档对象。
根据 JSON Schema 生成前端代码
在转换为 JSON Schema 后，我们可以使用 openapi3-util 生成前端代码。openapi3-util 提供了两种生成代码方式，即 generateRequest 和 generateResponse。前者用于生成发送请求的代码，后者用于生成处理响应的代码。例如，以下是使用 generateRequest 生成 axios 发送请求代码的示例：
const openapi3Util = require('openapi3-util');
const axios = require('axios');
const schema = openapi3Util.convert(openapiDocument);
const requestFn = openapi3Util.generateRequest(schema, 'getPetById');
const response = await axios(requestFn({petId: '123'}));其中，getPetById 为需要发送请求的接口名称。
如果你需要将请求发送给其他请求库，也可以使用 generateRequest 返回的函数，手动发送请求。
至于 generateResponse 函数，它可以帮助我们将 API 响应体的各个字段映射到前端代码中对应的类型，方便我们在开发过程中进行自动补全等操作。
示例
以下示例为一个简单的 GET 接口的 OpenAPI 规范：
-- -------------------- ---- -------
-------- -----
-----
------ ----
-------- -----
------
-------------
----
-------- ------
------------ ----------
-----------
- ----- -----
--- ----
--------- ----
------------ -- --
-------
----- ------
----------
------
------------ --
--------
-----------------
-------
----- ------
-----------
--------
----- ------
-------
----- ------我们可以使用 openapi3-util 将该规范转为 JSON Schema，并生成相应的前端代码：
-- -------------------- ---- ------- ----- ------------ - ------------------------- ----- ----- - ----------------- ----- --------------- - -- ------- ---- --- ----- ------ - -------------------------------------- ----- --------- - ------------------------------------ -------------- ----- ---------- - ------------------------------------- ------------- ------- ----- -------- ---------- - ----- -------- - ----- ----------------------- --------- ----- --------- ------- - -------------------------- -------------------- -------- -
如上所示，我们定义了两个函数 requestFn 和 responseFn。前者用于生成发送请求的函数，后者用于处理响应体。最后，我们使用 axios 发送请求，并使用 responseFn 函数将响应体映射成前端代码中的类型。
结语
OpenAPI 3.0 规范为 API 设计师、服务端工程师以及前端工程师提供了统一的接口描述标准。而 openapi3-util 则为前端工程师使用 OpenAPI 规范提供了方便的工具。使用 openapi3-util，可以让前端工程师更加方便地使用 OpenAPI 规范，提高开发效率。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60056bd281e8991b448e574a