Postman 如何使用 JSON Schema

The Postman API 平台 提供了一套丰富的解决方案，适用于 API 生命周期 的每个步骤。多年来，我们一直从前排见证了 JSON Schema 如何进入这个领域，并成为描述和注释 JSON 文档的行业标准。尽管许多替代方案不断出现又消失，但 JSON Schema 无疑证明了其作为 API 规范运动背后强大且可扩展的基础地位。根据 Postman 的 2022 年 API 状态报告，令人印象深刻的 72% 的受访者选择了 JSON Schema 作为他们首选的 API 规范。

由于 JSON Schema 在当今 API 的开发方式中根深蒂固，因此在 Postman 组织或 Postman API 平台中很难找到一个与 JSON Schema 无关的地方。随着 API 首先生成 开发的现代（和不断增长）重要性，使用 API 规范在设计和共享 API 中发挥着至关重要的作用。JSON Schema 目前是世界上最流行的 API 规范技术的支柱，包括 OpenAPI、AsyncAPI 和 RAML。

Postman 组织中的 JSON Schema

Postman 如何使用 JSON Schema 来构建自己的 API

Postman 运行着一个复杂的分布式系统，该系统由数十个微服务组成，为使 Postman API 平台成为可能的云工具提供支持。这些微服务利用 JSON Schema 通过独立的 JSON Schema 定义或 OpenAPI 和 AsyncAPI 规范来建模其接口。许多这些微服务还在后台使用 JSON Schema 来验证内部数据结构和配置文件，以及通过断言预期响应或从 JSON Schema 定义自动生成输入数据来执行端到端测试。作为一家 Node.js 公司，Postman 已开始努力分析如何依靠 TypeScript 注释从我们的代码库中自动生成 OpenAPI 和 AsyncAPI 定义。

鉴于 API 规范对于管理 Postman 分布式系统的重要性，2021 年，一个全面的内部研究项目旨在了解内部 Postman 平台中运行的微服务引入的各种 JSON Schema 定义。根据可重用性、相似性程度、唯一性比率和内容类型等特征对相应的 JSON Schema 定义进行了分析。为了提高可重用性和可发现性，Postman 正在探索一个新微服务的概念，该微服务充当中央 JSON Schema 目录 API。

为了分析目的，Postman 定期从支持 Postman API 平台的每个基于 SQL 的数据库中提取数据。为了适应我们服务中的模式更改，Postman 会自动将 SQL 表定义转换为 JSON Schema 定义，并将行转换为 JSON 文档，然后将它们聚合到 Postman 的内部数据仓库中。一些初步的实验已经进行，以探索从 JSON Schema 文档生成 SQL 表定义，从而使后者成为真理的来源。

JSON Schema 在 API 以外的用例

Postman 组织中 JSON Schema 的使用并不局限于其后端服务。例如，流行的 Postman 集合 基于 JSON 的数据格式是使用 JSON Schema 正式定义的。Postman 的 Newman 命令行集合运行器使用 JSON Schema 来验证自定义报告器的预期输出。Postman 的内部跨平台桌面框架使用 JSON Schema 来验证和注释配置文件，这些配置文件声明了桌面应用程序的各种变体（稳定版、Canary 版等）。Postman 还维护内部 C4 图，这些图使用 JSON 定义并使用 JSON Schema 验证 Postman 架构。

在 2022 年初，Postman 发布了对 gRPC 和 Protocol Buffers 的支持。在内部，Postman 可以将 Protocol Buffers 模式定义转换为 JSON Schema 定义，反之亦然。与 Protocol Buffers 模式相对应的 JSON Schema 定义用于在 gRPC 负载组合器编辑器中提供类型提示和自动完成，以验证用户输入并为测试目的生成与 Protocol Buffers 模式匹配的随机数据。这种方法使 Postman 能够在单个统一模式语言：JSON Schema 之上实现上述功能。

Postman API 平台中的 JSON Schema

JSON Schema 不仅在内部用于开发 Postman API 平台的各个组件，Postman 提供的许多功能都直接涉及 JSON Schema 的使用。

Postman 集合中的 JSON Schema

Postman 应用程序可以用来 将越来越多的 API 规范格式转换为 Postman 集合。如本文前面所述，最流行的 API 规范格式（如 OpenAPI、Swagger 和 RAML）依赖于 JSON Schema。在许多情况下，API 规范转换逻辑需要生成与 JSON Schema 定义匹配的随机 JSON 文档。

在定义 Postman 集合时，用户可以定义基于 JavaScript 的测试和预请求脚本，这些脚本在运行相应的集合时会自动执行。Postman 中嵌入的用于运行这些脚本的 JavaScript 引擎与流行的 AJV JSON Schema 验证器集成。借助它，Postman 用户编写脚本，这些脚本使用各种 JSON Schema 规范版本来执行 JSON Schema 验证。

OpenAPI 中的 JSON Schema

Postman 应用程序提供了一个丰富的 OpenAPI 编辑器，具有高级 JSON Schema 功能。编辑器能够显示自动完成和语法警告，它还突出显示了 关于 JSON Schema 和 OpenAPI 端点定义的可读性和安全性方面的潜在改进领域。然后使用 OpenAPI 定义来生成 可用端点及其各自 JSON Schema 定义的丰富文档，并选择性地生成匹配的 服务器代码（用 Go、Java、Python 和 Node.js 编写）。

使用 Postman 定义的 API 不仅仅是其 API 定义。它还有周围的元素，如文档、测试、模拟服务器和监控器。在编写 OpenAPI 规范时，Postman 将 交叉检查每个元素的完整性，以确保它们与 API 规范中包含的 JSON Schema 定义相匹配。

Postman API 网络

Postman API 平台的一个关键组件是 Postman API 网络，它是 世界上最大的公共 API 中心。这个全球公共注册表包含大量 API 及其相应的 JSON Schema 定义，通常由其各自的原始作者维护。一些值得注意的示例包括 Slack Web API、Docker HUB API 和 Twilio API。因此，Postman API 网络是生产级 JSON Schema 定义的最大数据集之一。

Postman 和 JSON Schema

由于 JSON Schema 是 Postman API 平台和 API 生态系统的重要组成部分，Postman 很荣幸能够作为 OpenJS 基金会 的一部分来支持 JSON Schema 组织，并帮助一些充满激情的核心贡献者加入 - Ben Hutton、Greg Dennis、Jason Desrosiers 和 Julian Berman - 作为 Postmanauts。我们无法了解未来的所有情况，但 Postman 确信 API 的未来与 JSON Schema 密切相关。