OpenAPI 和 JSON Schema：何时使用哪个

OpenAPI v3.0 是 API 设计社区向前迈出的一大步。它扩展并改进了设计优先流程和自动化。它简化了定义以提高可重用性，同时支持更多安全方案。最大的新增功能之一是组件。虽然这些组件改进了以前的 JSON Schema 支持，但 OpenAPI v3.0 仍然需要开发人员弥补其不兼容性。

许多组织都有由 JSON Schema 描述的现有对象。但问题是，开发人员遇到了一个大问题：OpenAPI仍然无法识别和支持某些 JSON Schema 关键字。

兼容性问题简述：OpenAPI v2.0 是 JSON Schema 的扩展子集。存在分歧，导致与 JSON Schema Draft 4 的兼容性约为 80%。OpenAPI v3.0 使与 JSON Schema Draft 5 的兼容性达到 90%。简而言之，截至撰写本文时，开发人员从未能够在不避开不兼容性的情况下使用 JSON Schema。

目前正在进行激烈的讨论以缓解这一问题，使其与 JSON Schema 的最新草案（Draft 2019-09）完全兼容，但目前，我们需要学习如何使用这两种最新格式，并了解它们如何以及何时可以协同工作。

什么是JSON Schema 文档？

在我们深入讨论细节之前，让我们先快速了解一下 JSON Schema 是什么以及它是如何使用的，以消除任何疑惑。

首先，模式的定义是一种数据结构或模板。它本身不是数据库，也不是数据的 JSON 文档。模式的最大优势在于它允许团队规划和迭代其数据的结构。就格式达成一致有助于团队协作并减少错误。例如，客户端和服务器端团队可以在没有包含实时数据的完整 API 的情况下互相提供反馈并测试用例。

JSON Schema 通常用于 API，但它仅描述数据本身。这意味着，您也可以以其他方式使用该格式。模式还有助于将数据库构造为可重复使用的块，以提高效率和可操作性。在您需要验证 JSON 数据是否符合定义的模式的任何地方，JSON Schema 都会有所帮助。

什么是OpenAPI？

OpenAPI 是多种 API 规范格式的名称。OpenAPI v2.0 在捐赠给 OpenAPI Initiative 之前被称为 Swagger。该行业专家小组随后创建了 OpenAPI v3.0。两者都是 REST/HTTP API 的描述格式，允许您映射 API 的输入/输出参数、端点和身份验证方法。

与 JSON Schema 不同，OpenAPI 文档是整个 API 的定义，而不仅仅是数据模型。在创建之前，许多 API 的设计都无法映射其工作方式或验证其是否按预期运行。借助这种机器可读的描述，您还可以生成对人类有用的工具，例如文档和模拟服务器。

您可以使用 JSON Schema 来描述请求和响应的数据对象。但是，OpenAPI 包括这些请求和响应的格式。同样，您可以使用 JSON Schema 模拟 API 响应，但您需要像 OpenAPI 这样的工具来生成整个模拟服务器。

如何将 OpenAPI 和 JSON Schema结合使用？

分别了解了这些格式后，让我们继续了解如何以及何时可以结合使用 OpenAPI 和 JSON Schema。这里将引用 Stoplight 的 Phil Sturgeon 所做的大量出色工作，他提出了一些快速解决方案，这些方案也将帮助我们了解如何将这些强大的工具结合在一起的基础知识。

继续使用 JSON 模式

如果您已经使用 JSON Schema 来描述数据对象，则无需进行更改。OpenAPI 和 JSON Schema 之间的差异希望只是短期问题。使用与 OpenAPI 3.0 兼容的 JSON Schema 版本可能会影响其他领域，因此请关注后续更改。

您需要将现有的 JSON Schema 转换为包含 OpenAPI 支持的关键字的 Schema。作为想要遵循此快速解决方案的 API 架构师，这意味着纯 JSON Schema 草稿将成为您数据模型的 Rosetta Stone。接下来，您将创建一个使用 JSON Schema 编写的版本，该版本可与 OpenAPI 配合使用。这是一个额外的步骤，但有一些工具可以为您提供支持。

将 JSON 架构转换为 OpenAPI 架构

需要额外的工具来维护 JSON Schema 和 OpenAPI 之间的和谐并不是理想的做法。也就是说，当后续版本兼容时，撤销修复将更容易。

使用简单的NPM 包，将 JSON Schema 转换为 OpenAPI Schema 对象。您可以在上述 GitHub 存储库中找到有关其所做转换的详细描述，但这里有一个包含类型和可空值的简单示例：

const toOpenApi = require('json-schema-to-openapi-schema');



const schema = {

  $schema: 'http://json-schema.org/draft-04/schema#',

  type: ['string', 'null'],

  format: 'date-time',

};



console.log(toOpenApi(schema));

该示例打印出：

{

  type: 'string',

  format: 'date-time',

  nullable: true

}

请记住，此包基于JSON Schema v5.0 – 因此请确保您使用该版本或更高版本。

总结

OpenAPI v3.0 既是 JSON Schema Draft 5 的子集，又是超集，这让开发人员感到困惑。

换句话说，未来仍然存在分歧，但正在越来越近。根据上述拉取请求中的讨论，以下是仍需在 OpenAPI v3.1 中支持的 JSON Schema 2019-09 关键字：

nullable
discriminator
xml
example

此外，还有关于 exclusiveMinimum 和 exclusiveMaximum 使用的说明。如需深入了解，您可以阅读 Phil关于该主题的文章。他深入探讨了架构和规范之间的具体差异。主要目标是在 OpenAPI 3.1 中编写标准 JSON Schema，而不会出现奇怪的错误。不再需要变通方法或转换。

此外，工具供应商将能够使用 JSON Schema 验证器来替换他们在项目“OpenAPI 友好”版本中用作占位符的任何快速修复 OpenAPI 验证器。

如果在实施这一想法的过程中没有出现意外问题，我们将看到该提案作为 OpenAPI v3.1 中的一个功能出现，并朝着彻底解决“分歧”问题迈出又一步。

原文链接：OpenAPI and JSON Schema: When to Use Which