什么是JSON模式 ？ 它提供了描述任何JSON值的結(jié)構(gòu)和屬性的詳盡方法。 在記錄對(duì)任何JSON API的請(qǐng)求和響應(yīng)時(shí)，它非常有用。 本文將探討其在API的軟件開(kāi)發(fā)周期中的作用。

記錄JSON響應(yīng)格式

定義數(shù)據(jù)架構(gòu)的最明顯的用例也許是在記錄API響應(yīng)的結(jié)構(gòu)。

讓我們來(lái)看一本書(shū)API的簡(jiǎn)單響應(yīng)：

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

我們可以使用以下JSON模式文檔描述這些響應(yīng)的結(jié)構(gòu)：

{"$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使用者可以從上述內(nèi)容中找到有用的參考，以了解哪些字段可用以及他們存儲(chǔ)的數(shù)據(jù)類型。

為了使事情變得更加正式，我們甚至可以添加一個(gè)自定義響應(yīng)標(biāo)頭，其中包含指向我們的架構(gòu)文檔的鏈接。 這是發(fā)送自定義標(biāo)頭的PHP示例：

; rel="describedby"');

我強(qiáng)烈建議JSON Schema作者使用該指南，以獲取比常規(guī)JSON Schema網(wǎng)站上更多的討論和示例。

記錄JSON請(qǐng)求格式

也許比記錄響應(yīng)格式更有價(jià)值的是記錄請(qǐng)求格式。 您可能會(huì)通過(guò)反復(fù)試驗(yàn)來(lái)弄清楚響應(yīng)是什么樣的，但是幾乎不可能猜測(cè)將數(shù)據(jù)發(fā)布到端點(diǎn)時(shí)需要哪種格式。

更糟糕的是，沒(méi)有標(biāo)準(zhǔn)的地方可以鏈接到必要的架構(gòu)。 您可以在錯(cuò)誤消息中引用架構(gòu)，但是我們很快就會(huì)發(fā)現(xiàn)需要一種將JSON架構(gòu)與路由和請(qǐng)求方法聯(lián)系起來(lái)的組織方法。 這就是為什么我們有用于API的組織工具的原因。

API Blueprint ， RAML和Open API Spec （以前稱為Swagger ）是用于記錄API的最常用工具。 它們都提供對(duì)JSON Schema定義的支持，盡管程度不同。

注冊(cè)免費(fèi)的Codeship帳戶

開(kāi)發(fā)人員的理想工作流程

最終，我們開(kāi)發(fā)人員想要的是一個(gè)更簡(jiǎn)單的工作流程。 理想情況下，我們需要一種解決以下問(wèn)題的解決方案：

一種真理來(lái)源（一個(gè)地方更新定義）。 如果我們對(duì)于API中涉及的每種數(shù)據(jù)類型都有JSON模式文檔，并且可以從API工具中引用該模式，那么對(duì)于所有用例，我們將完成一個(gè)真實(shí)的來(lái)源。 校驗(yàn)！

快速原型制作。 使用任何一致的API工具都會(huì)使我們能夠快速進(jìn)行原型制作。 像Apiary這樣的服務(wù)會(huì)消耗Swagger或API Blueprint文件，并且可以充當(dāng)模擬API！ 一旦您對(duì)響應(yīng)的模式達(dá)成共識(shí)，前端團(tuán)隊(duì)就可以編寫(xiě)用于格式化響應(yīng)的代碼，而后端團(tuán)隊(duì)可以針對(duì)將獲取原始數(shù)據(jù)并將其返回給客戶端的代碼進(jìn)行工作。給定的格式。 校驗(yàn)！

生成文檔。 如果我們有一個(gè)結(jié)構(gòu)合理的API路由文檔，包括其中的數(shù)據(jù)結(jié)構(gòu)的JSON模式，那么將標(biāo)題，描述和示例提取到可讀文檔中相對(duì)容易（是的，有很多工具可以這個(gè)）。 校驗(yàn)！

在發(fā)送有效負(fù)載之前，先對(duì)其進(jìn)行驗(yàn)證。 JSON模式驗(yàn)證器幾乎以每種語(yǔ)言編寫(xiě)。 您可以在客戶端上使用它們?cè)谟行ж?fù)載發(fā)送之前對(duì)其進(jìn)行驗(yàn)證，或者在執(zhí)行業(yè)務(wù)邏輯驗(yàn)證之前在服務(wù)器端使用它們進(jìn)行格式驗(yàn)證。 校驗(yàn)！

根據(jù)其文檔測(cè)試API。 如果我們有一個(gè)全面的工具來(lái)記錄每個(gè)路由和方法以及響應(yīng)或有效負(fù)載的JSON模式，那么想象一下遍歷已定義的路由并驗(yàn)證它們是否接受和/或返回對(duì)象就可以了。與定義的JSON模式格式匹配。 Dredd是為我們完成此作業(yè)的一個(gè)NPM軟件包：它根據(jù)其文檔對(duì)API進(jìn)行了驗(yàn)證（當(dāng)前它支持Swagger和AP??I藍(lán)圖）。 Abao是一個(gè)為RAML定義執(zhí)行此任務(wù)的軟件包。 校驗(yàn)！

生成SDK。 每個(gè)大型API工具都支持生成SDK代碼以訪問(wèn)API。 校驗(yàn)！

考慮到所有這些綠燈，我們似乎生活在開(kāi)發(fā)者的幻想世界中，那里一切完美！ 好吧，正如菲爾·斯特金 （ Phil Sturgeon）在他關(guān)于該主題的出色文章中打趣的那樣，我們“血腥親密”，但我們還遠(yuǎn)遠(yuǎn)不夠。

我想假設(shè)，任何API工具中最嚴(yán)重的缺點(diǎn)都與該工具實(shí)現(xiàn)JSON Schema規(guī)范的方式有多徹底。 這并不是說(shuō)只要API工具完全實(shí)現(xiàn)JSON Schema，一切都很棒而且完美。 但是，遵循JSON Schema規(guī)范可以避免最嚴(yán)重的問(wèn)題-與解決體系結(jié)構(gòu)上的不可能性相比，我們可以更輕松地解決美學(xué)問(wèn)題。

讓我們回顧一下我們的三個(gè)主要API工具選項(xiàng)如何幫助或阻礙理想的工作流程。

API藍(lán)圖缺點(diǎn)

盡管這是一個(gè)受歡迎且受支持的工具， 但確實(shí)可以讓您引用JSON模式來(lái)指示請(qǐng)求或響應(yīng)格式，但它確實(shí)難以包含多個(gè)文件。 當(dāng)涉及單一的真相來(lái)源時(shí)（上述清單中的項(xiàng)目1），這就構(gòu)成了一個(gè)主要問(wèn)題。 如果您的兩個(gè)或多個(gè)API端點(diǎn)返回相同模式的響應(yīng)怎么辦？ 如果我們想要一個(gè)單一的事實(shí)來(lái)源，那么所有端點(diǎn)都應(yīng)該引用同一個(gè)文件。

有解決此問(wèn)題的方法-其他人已記錄了使用API?? Blueprint中的多個(gè)文件的方法。 JSON Schema已經(jīng)支持一個(gè)功能強(qiáng)大的$ref關(guān)鍵字，該關(guān)鍵字可以充當(dāng)“ include”語(yǔ)句，因此，如果API Blueprint可以利用此功能，那就太好了。

拉姆

RAML確實(shí)支持通過(guò)自己的!includes指令包含多個(gè)文件，因此它可以輕松地從多個(gè)位置引用同一模式文件。 它還完全支持JSON模式規(guī)范及其強(qiáng)大的$ref參數(shù)，因此模式可以毫無(wú)問(wèn)題地引用子模式或遠(yuǎn)程模式。

我所見(jiàn)過(guò)的有關(guān)RAML的大多數(shù)投訴都與其文檔生成的樣式有關(guān)（上面列表中的項(xiàng)目3），或者它僅以YAML表示而不具有JSON選項(xiàng)，這兩者都是很膚淺的事實(shí)。 。 其結(jié)構(gòu)與Swagger的差異很小。

關(guān)于RAML唯一令我困惑的是為什么它沒(méi)有被更廣泛地采用。 可以很好地滿足我們理想的開(kāi)發(fā)人員工作流程的要求。

招搖及其局限性

不論好壞，Swagger都具有吸引人的元素，因此似乎是風(fēng)在吹拂的地方。 但是，由于缺乏對(duì)JSON Schema標(biāo)準(zhǔn)的支持，它確實(shí)遭受了一些無(wú)用的限制（您猜對(duì)了）。

馬上，如果您擁有定義良好且100％有效的JSON Schema文檔來(lái)描述API中的所有內(nèi)容，那么Swagger將不起作用 。 沒(méi)錯(cuò)：Swagger 2.0僅支持部分 （但不是全部）JSON Schema關(guān)鍵字，并且不能保證Open API 3.0（Swagger的下一個(gè)迭代）可以解決所有缺點(diǎn)。 實(shí)現(xiàn)一些已經(jīng)存在多年的JSON Schema功能非常困難，更不用說(shuō)計(jì)劃即將發(fā)布的新功能了。

由于JSON Schema已經(jīng)存在很長(zhǎng)時(shí)間了，所以可以公平地說(shuō)Swagger在尊重長(zhǎng)輩方面做得并不出色。 JSON Schema文檔已經(jīng)充分描述了Swagger規(guī)范（及其Open API替代），因此，當(dāng)車輪明顯無(wú)法滾動(dòng)時(shí)，重新發(fā)明輪子似乎會(huì)適得其反。 例如，為什么我們必須依靠氣質(zhì)的在線編輯器來(lái)驗(yàn)證我們的模式？

讓我們?cè)O(shè)置一些警告標(biāo)志，以便您了解一些地雷。 例如，Swagger不允許您的模式聲明其寫(xiě)入的JSON模式版本。這是使用$schema關(guān)鍵字完成的，但是Swagger不支持它。

另一個(gè)痛苦的缺點(diǎn)是Swagger尚不支持可為空字段的概念。 用JSON模式的話，字段可以定義為類型數(shù)組 ， 例如 {"type": ["string", "null"]} ，以指示可為空的字符串。 如果Swagger遇到這個(gè)完全有效的JSON Schema約定，它將窒息。 不好！

JSON模式的patternProperties關(guān)鍵字對(duì)于通過(guò)正則表達(dá)式將值映射到模式非常有用，但是您猜到了，Swagger不支持它。

另一個(gè)缺點(diǎn)是它缺乏對(duì)模式的“ id”（或“ $ id”）屬性的支持。 用JSON模式的話來(lái)說(shuō)，模式的ID有點(diǎn)像命名空間，因此可以將引用的模式適當(dāng)?shù)乩斫鉃楦改Ｊ较碌淖幽Ｊ交颡?dú)立的定義。 因此，如果您引用的模式使用$ref指向另一個(gè)模式，請(qǐng)當(dāng)心！ 昂首闊步可能不贊成。 這會(huì)使將您的定義分布到多個(gè)文件中變得極為困難。 Swagger似乎更喜歡所有可重用的定義都存儲(chǔ)在根文檔的definitions對(duì)象中，但這在處理多文件設(shè)置時(shí)幾乎不可行。

最具挑戰(zhàn)性的定義之一涉及“循環(huán)引用”，其中一種數(shù)據(jù)類型的實(shí)例可能包含子屬性，這些子屬性是同一數(shù)據(jù)類型的實(shí)例。 公平地講，無(wú)論您使用哪種API工具，這都是棘手的，但是當(dāng)該工具在背后支持JSON Schema功能時(shí)，變得特別困難。

歸根結(jié)底，您可以讓Swagger發(fā)揮作用，但是您必須在其限制范圍內(nèi)進(jìn)行操作。 至少，這意味著破壞JSON Schema文檔，有時(shí)這意味著要任意施加可能無(wú)法準(zhǔn)確描述您的API的限制。 我們冒著違反神圣清單中第3、4和5項(xiàng)的風(fēng)險(xiǎn)。

隨著時(shí)間的推移維護(hù)您的API定義

無(wú)論您使用哪種API工具來(lái)開(kāi)發(fā)API，最終都需要對(duì)其進(jìn)行維護(hù)。 當(dāng)您的定義分散在多個(gè)文件中時(shí)，此任務(wù)通常會(huì)更容易。 RAML輕松支持這一點(diǎn)，而Swagger可以做一些警告。

請(qǐng)參閱有關(guān)將Swagger定義拆分為多個(gè)文件的本文 。 在探索過(guò)程中，我編寫(xiě)了一個(gè)Github存儲(chǔ)庫(kù)，其中包含一些多文件Swagger示例 ，您可能會(huì)找到一些有用的參考。

測(cè)試您的API

只要您的API工具定義了應(yīng)用程序的路由和方法，就可以簡(jiǎn)單地遍歷它們并訪問(wèn)這些終結(jié)點(diǎn)以驗(yàn)證它們是否按照他們說(shuō)的去做。 如前所述， Dredd和Abao是執(zhí)行此乏味任務(wù)的兩個(gè)NPM軟件包。 主要目標(biāo)是輕松驗(yàn)證您的API是否達(dá)到了預(yù)期的效果，如果您正在使用測(cè)試驅(qū)動(dòng)的開(kāi)發(fā)（TDD或BDD），它也是一個(gè)很好的起點(diǎn)。

摘要

由于Swagger似乎很受歡迎，因此我可能需要花一些時(shí)間來(lái)考慮RAML或API Blueprint的消失的可能性，但實(shí)際上，沒(méi)有任何一種解決方案能夠完全滿足我作為開(kāi)發(fā)人員的需求。

我認(rèn)為我們正處于實(shí)現(xiàn)這一目標(biāo)的風(fēng)口浪尖，但是只有當(dāng)其中一種工具完全實(shí)現(xiàn)了已經(jīng)具有豐富功能的JSON Schema標(biāo)準(zhǔn)時(shí)，我們才真正擁有我們尋求的自由。 我認(rèn)為Open API標(biāo)準(zhǔn)正朝著這個(gè)方向發(fā)展，只要這些工具之一到達(dá)那個(gè)目的地，我將很樂(lè)意在下一個(gè)API中使用它。

翻譯自: https://www.javacodegeeks.com/2017/11/json-schemas-role-building-deploying-api.html

總結(jié)

以上是生活随笔為你收集整理的JSON模式在构建和部署API中的作用的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。