JSON模式在构建和部署API中的作用

什么是JSON模式？它提供了描述任何JSON值的结构和属性的详尽方法。在记录对任何JSON API的请求和响应时，它非常有用。本文将探讨其在API的软件开发周期中的作用。

记录JSON响应格式

定义数据架构的最明显的用例也许是在记录API响应的结构。

让我们来看一本书API的简单响应：

{"title": "The Art of Lying","pages": 412,"is_fiction": true,"status": "published","updated_at": "2017-04-12T23:20:50.52Z"
}

我们可以使用以下JSON模式文档描述这些响应的结构：

{"$schema": "http://json-schema.org/draft-04/schema#""title": "Book","description": "Describes a book in our online database","type": "object","properties": {"title": {"description": "The title of the book""type": "string","minLength": 1},"pages": {"type": "integer","minimum": 1},"is_fiction": {"type": "boolean"},"updated_at": {"type": "string","format": "date-time"}},"additionalProperties": false
}

我们的API使用者可以从上述内容中找到有用的参考，以了解哪些字段可用以及他们存储的数据类型。

为了使事情变得更加正式，我们甚至可以添加一个自定义响应标头，其中包含指向我们的架构文档的链接。这是发送自定义标头的PHP示例：

; rel="describedby"');

我强烈建议JSON Schema作者使用该指南，以获取比常规JSON Schema网站上更多的讨论和示例。

记录JSON请求格式

也许比记录响应格式更有价值的是记录请求格式。您可能会通过反复试验来弄清楚响应是什么样的，但是几乎不可能猜测将数据发布到端点时需要哪种格式。

更糟糕的是，没有标准的地方可以链接到必要的架构。您可以在错误消息中引用架构，但是我们很快就会发现需要一种将JSON架构与路由和请求方法联系起来的组织方法。这就是为什么我们有用于API的组织工具的原因。

API Blueprint ， RAML和Open API Spec （以前称为Swagger ）是用于记录API的最常用工具。它们都提供对JSON Schema定义的支持，尽管程度不同。

注册免费的Codeship帐户

开发人员的理想工作流程

最终，我们开发人员想要的是一个更简单的工作流程。理想情况下，我们需要一种解决以下问题的解决方案：

一种真理来源（一个地方更新定义）。 如果我们对于API中涉及的每种数据类型都有JSON模式文档，并且可以从API工具中引用该模式，那么对于所有用例，我们将完成一个真实的来源。 校验！
快速原型制作。 使用任何一致的API工具都会使我们能够快速进行原型制作。像Apiary这样的服务会消耗Swagger或API Blueprint文件，并且可以充当模拟API！一旦您对响应的模式达成共识，前端团队就可以编写用于格式化响应的代码，而后端团队可以针对将获取原始数据并将其返回给客户端的代码进行工作。给定的格式。 校验！
生成文档。 如果我们有一个结构合理的API路由文档，包括其中的数据结构的JSON模式，那么将标题，描述和示例提取到可读文档中相对容易（是的，有很多工具可以这个）。 校验！
在发送有效负载之前，先对其进行验证。 JSON模式验证器几乎以每种语言编写。您可以在客户端上使用它们在有效负载发送之前对其进行验证，或者在执行业务逻辑验证之前在服务器端使用它们进行格式验证。 校验！
根据其文档测试API。 如果我们有一个全面的工具来记录每个路由和方法以及响应或有效负载的JSON模式，那么想象一下遍历已定义的路由并验证它们是否接受和/或返回对象就可以了。与定义的JSON模式格式匹配。 Dredd是为我们完成此作业的一个NPM软件包：它根据其文档对API进行了验证（当前它支持Swagger和API蓝图）。 Abao是一个为RAML定义执行此任务的软件包。 校验！
生成SDK。 每个大型API工具都支持生成SDK代码以访问API。 校验！

考虑到所有这些绿灯，我们似乎生活在开发者的幻想世界中，那里一切完美！好吧，正如菲尔·斯特金（ Phil Sturgeon）在他关于该主题的出色文章中打趣的那样，我们“血腥亲密”，但我们还远远不够。

我想假设，任何API工具中最严重的缺点都与该工具实现JSON Schema规范的方式有多彻底。这并不是说只要API工具完全实现JSON Schema，一切都很棒而且完美。但是，遵循JSON Schema规范可以避免最严重的问题-与解决体系结构上的不可能性相比，我们可以更轻松地解决美学问题。

让我们回顾一下我们的三个主要API工具选项如何帮助或阻碍理想的工作流程。

API蓝图缺点

尽管这是一个受欢迎且受支持的工具， 但确实可以让您引用JSON模式来指示请求或响应格式，但它确实难以包含多个文件。当涉及单一的真相来源时（上述清单中的项目1），这就构成了一个主要问题。如果您的两个或多个API端点返回相同模式的响应怎么办？如果我们想要一个单一的事实来源，那么所有端点都应该引用同一个文件。

有解决此问题的方法-其他人已记录了使用API Blueprint中的多个文件的方法。 JSON Schema已经支持一个功能强大的$ref关键字，该关键字可以充当“ include”语句，因此，如果API Blueprint可以利用此功能，那就太好了。

拉姆

RAML确实支持通过自己的!includes指令包含多个文件，因此它可以轻松地从多个位置引用同一模式文件。它还完全支持JSON模式规范及其强大的$ref参数，因此模式可以毫无问题地引用子模式或远程模式。

我所见过的有关RAML的大多数投诉都与其文档生成的样式有关（上面列表中的项目3），或者它仅以YAML表示而不具有JSON选项，这两者都是很肤浅的事实。。其结构与Swagger的差异很小。

关于RAML唯一令我困惑的是为什么它没有被更广泛地采用。可以很好地满足我们理想的开发人员工作流程的要求。

招摇及其局限性

不论好坏，Swagger都具有吸引人的元素，因此似乎是风在吹拂的地方。但是，由于缺乏对JSON Schema标准的支持，它确实遭受了一些无用的限制（您猜对了）。

马上，如果您拥有定义良好且100％有效的JSON Schema文档来描述API中的所有内容，那么Swagger将不起作用 。没错：Swagger 2.0仅支持部分（但不是全部）JSON Schema关键字，并且不能保证Open API 3.0（Swagger的下一个迭代）可以解决所有缺点。实现一些已经存在多年的JSON Schema功能非常困难，更不用说计划即将发布的新功能了。

由于JSON Schema已经存在很长时间了，所以可以公平地说Swagger在尊重长辈方面做得并不出色。 JSON Schema文档已经充分描述了Swagger规范（及其Open API替代），因此，当车轮明显无法滚动时，重新发明轮子似乎会适得其反。例如，为什么我们必须依靠气质的在线编辑器来验证我们的模式？

让我们设置一些警告标志，以便您了解一些地雷。例如，Swagger不允许您的模式声明其写入的JSON模式版本。这是使用$schema关键字完成的，但是Swagger不支持它。

另一个痛苦的缺点是Swagger尚不支持可为空字段的概念。用JSON模式的话，字段可以定义为类型数组，例如 {"type": ["string", "null"]} ，以指示可为空的字符串。如果Swagger遇到这个完全有效的JSON Schema约定，它将窒息。不好！

JSON模式的patternProperties关键字对于通过正则表达式将值映射到模式非常有用，但是您猜到了，Swagger不支持它。

另一个缺点是它缺乏对模式的“ id”（或“ $ id”）属性的支持。用JSON模式的话来说，模式的ID有点像命名空间，因此可以将引用的模式适当地理解为父模式下的子模式或独立的定义。因此，如果您引用的模式使用$ref指向另一个模式，请当心！昂首阔步可能不赞成。这会使将您的定义分布到多个文件中变得极为困难。 Swagger似乎更喜欢所有可重用的定义都存储在根文档的definitions对象中，但这在处理多文件设置时几乎不可行。

最具挑战性的定义之一涉及“循环引用”，其中一种数据类型的实例可能包含子属性，这些子属性是同一数据类型的实例。公平地讲，无论您使用哪种API工具，这都是棘手的，但是当该工具在背后支持JSON Schema功能时，变得特别困难。

归根结底，您可以让Swagger发挥作用，但是您必须在其限制范围内进行操作。至少，这意味着破坏JSON Schema文档，有时这意味着要任意施加可能无法准确描述您的API的限制。我们冒着违反神圣清单中第3、4和5项的风险。

随着时间的推移维护您的API定义

无论您使用哪种API工具来开发API，最终都需要对其进行维护。当您的定义分散在多个文件中时，此任务通常会更容易。 RAML轻松支持这一点，而Swagger可以做一些警告。

请参阅有关将Swagger定义拆分为多个文件的本文。在探索过程中，我编写了一个Github存储库，其中包含一些多文件Swagger示例，您可能会找到一些有用的参考。

测试您的API

只要您的API工具定义了应用程序的路由和方法，就可以简单地遍历它们并访问这些终结点以验证它们是否按照他们说的去做。如前所述， Dredd和Abao是执行此乏味任务的两个NPM软件包。主要目标是轻松验证您的API是否达到了预期的效果，如果您正在使用测试驱动的开发（TDD或BDD），它也是一个很好的起点。