本文由 Green Turtle 的绿色科技顾问兼保护地球主席 Phil Sturgeon 撰写。如果您想捐赠给 Phil 选择的慈善机构，请访问保护地球，该机构正在逐步为英国重新造林。
OpenAPI v3.1.0 进行了许多重大改进，解决了诸如JSON Schema 对象和 OpenAPI Schema 对象之间的细微差别等问题，并增加了对 Webhooks 的支持。
升级工具可能很棘手，但与从 v2 升级到 v3.0 相比，这次升级应该会容易得多。为了减少工作量，我们为工具开发人员准备了一些便捷的资源，提供测试用例、示例和一般指导。
首先，以下文章将从用户的角度展示 v3.0 和 v3.1 之间的差异
您需要支持所有功能吗？
其中一些内容更多地针对最终用户及其需要执行的操作，但工具供应商需要做什么呢？
对于 Webhooks 等新功能，您可以问问自己：此工具是否需要支持 Webhooks？如果是文档工具，则可能需要！如果该工具正在验证传入服务器的 Web 请求，则可能不需要。
一些工具采用了 3.1.0 支持的定义，即“3.1.0 文档在同一工具中与 3.0.0 文档的效果相同”，这是一个良好的第一步。然后可以稍后添加对其他新关键字的支持。
我认为，让 3.1.0 文档在基本级别上能够工作比支持 3.1.0 中的每个功能都更重要。最终用户会随着时间的推移针对他们最感兴趣的部分提出功能请求。
JSON Schema 整合
对于其他大部分更改，区别在于，OpenAPI Schema 对象不再使用与 JSON Schema非常相似的 Schema 对象，而是直接使用 JSON Schema。这里有一些技术细节，从技术上讲，OpenAPI Schema 定义了自己的 JSON Schema 词汇表，该词汇表扩展了主要的 JSON Schema 词汇表，并增加了对discriminator的支持。由于在 3.1.0 中，discriminator的使用被明确为仅用于现有 oneOf、anyOf、allOf 的“提示”或快捷方式，因此绝大多数工具都可以安全地忽略它。
简而言之：您可以使用任何有效的 JSON Schema 工具来处理 OpenAPI 中schema:对象的内容，这意味着许多工具可以逐步减少对手工制作的 Schema 检查代码的依赖，并利用任何现有的JSON Schema 工具。
例如，如果您维护的工具以前在 JavaScript 中手动验证 OpenAPI Schema，那么可以考虑将其包装在if ($version == "3.0")语句中，使用旧逻辑，将其弃用，然后如果版本为 3.1，则可以使用功能强大的工具（如AJV或HyperJump）来完成所有繁重的工作。这样，您的工具可以直接从这些工具中受益，因为它们为您完成了所有支持现代 JSON Schema/OAS3.1 关键字的工作，例如if/then/else。
这也意味着它们可以承担 JSON Schema 成熟为稳定版本时所带来的其他更改的繁重工作（尽管如果您也能提供帮助，那将是非常棒的）。
测试用例
要确保您的工具能够与 OpenAPI v3.1 配合使用，您需要一些 OpenAPI v3.1 文档来进行测试。目前还没有官方的 OpenAPI v3.1 文档列表，但社区编写了一些示例文件，这些文件可用于测试套件中以显示成功或失败的场景
验证 Schema
许多工具使用 JSON Schema 文档来描述有效的 OpenAPI 文档。是的，这句话非常拗口，但如果您知道我的意思，那么您可能想知道 OpenAPI v3.1 是否有新的 JSON Schema 文档？好消息是，有！
要了解其他 OpenAPI 工具的进展情况，请查看OpenAPI.Tools。也许您可以利用其他一些工具，或与一些开发人员合作，或向他们提问，或聘用他们来处理您的工作等等。
别忘了向 OpenAPI.Tools 发送pull request，说明您何时支持 v3.1，方法是在_data/tools.yml中添加v3_1: true。您还可以添加openapi31标签到 GitHub 上，以便其他工具聚合器也能找到您！
展开所有返回顶部转到底部
