前言
Swagger 是一个用于描述、生产、消费 RESTful Web 服务的标准，它定义了 API 所需的各种元素，它的 JSON Schema 描述至关重要，schema 描述了 API 的输入输出参数的格式、数据类型、限制等。
Swagger 官方提供了一个 npm 包 swagger-schema-official，它将 JSON Schema 转换成 Swagger schemas，我们可以借助这个包生成包含 API 输入输出格式的 Swagger 文档，方便服务的调用与测试。
本文将介绍如何使用 swagger-schema-official 生成 Swagger schemas，同时还会介绍如何将生成的 Swagger schema 转换为 Swagger 文档和从 Swagger JSON 生成 TypeScript 类型。
安装
我们可以在 npm 上找到 swagger-schema-official，安装命令如下：
npm install swagger-schema-official --save-dev
使用示例
我们以一个简单的 API 为例，API 的输入为一个包含 name 和 age 字段的对象，输出为一个包含 message 字段的对象，其中 message 的内容为输入对象的字符串拼接。
首先，我们定义输入输出的 JSON Schema，定义于 input-schema.json 和 output-schema.json。input-schema.json 如下：
-- -------------------- ---- -------
-
------ ----------------------------------
------- ---------
------------- -
------- -
------- --------
--
------ -
------- --------
--
-------- -
------- --------
-
--
----------- -
-------
-----
-
-output-schema.json 如下：
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}然后，我们通过运行以下代码，生成 Swagger JSON：
const SwaggerSchemaOfficial = require('swagger-schema-official');
const inputSchema = require('./input-schema.json');
const outputSchema = require('./output-schema.json');
const swaggerSchema = SwaggerSchemaOfficial(inputSchema, outputSchema);
console.log(JSON.stringify(swaggerSchema, null, 2));这里我们使用 require 将 input-schema.json 和 output-schema.json 中的 JSON Schema 引入；然后我们将它们传给 SwaggerSchemaOfficial 函数，生成 Swagger Schema，并将 Swagger Schema 转换成 JSON 字符串输出：
-- -------------------- ---- -------
-
------- ---------
------------- -
---------- -
------- --------
-
--
-------------- -
------ ----------------------------------
------- ---------
------------- -
------- -
------- --------
--
------ -
------- --------
--
-------- -
------- --------
-
--
----------- -
-------
-----
-
-
-从上面的结构可以看出，Swagger Schema 会将输入输出的 JSON Schema 整合在一起，方便消费。
最后，我们可以通过使用 Swagger UI 将生成的 Swagger JSON 转换成 Swagger 文档，或者使用 openapi-types 将 Swagger JSON 转换成 TypeScript 定义，这里暂不赘述。
总结
本文介绍了如何使用 swagger-schema-official 生成 Swagger schemas，同时也简单介绍了如何将 Swagger schemas 转换成 Swagger 文档和 TypeScript 定义，相信读者已经对于如何使用 swagger-schema-official 熟知，可以很好地应用于自己的项目中，提升 API 的可用性、可测试性及可读性。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/201889