json api

什么是JSON模式 ？ 它提供了一種描述任何JSON值的結構和屬性的徹底方法。 在記錄對任何JSON API的請求和響應時，它非常有用。 本文將探討其在API的軟件開發(fā)周期中的作用。

記錄JSON響應格式

定義數(shù)據(jù)架構的最明顯的用例也許是在記錄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使用者可以從上面找到有用的參考資料，以了解哪些字段可用以及它們存儲的數(shù)據(jù)類型。

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

; rel="describedby"');

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

記錄JSON請求格式

可能比記錄響應格式更有價值的是記錄請求格式。 您可能會通過反復試驗弄清楚響應是什么樣的，但是幾乎不可能猜測將數(shù)據(jù)發(fā)布到端點時需要哪種格式。

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

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

注冊免費的Codeship帳戶

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

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

一種真理來源（一個地方更新定義）。 如果我們對于API中涉及的每種數(shù)據(jù)類型都有JSON模式文檔，并且可以從我們的API工具中引用該模式，那么我們將為所有用例完成一個單一的事實來源。 檢查！

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

生成文檔。 如果我們有一個結構合理的API路由文檔，包括其中的數(shù)據(jù)結構的JSON模式，那么將標題，描述和示例提取到可讀文檔中相對容易（是的，有很多工具可以這個）。 檢查！

在發(fā)送有效負載之前，先對其進行驗證。 JSON模式驗證器幾乎以每種語言編寫。 您可以使用它們在客戶端在有效負載發(fā)送之前對其進行驗證，或者在執(zhí)行業(yè)務邏輯驗證之前在服務器端使用它們進行格式驗證。 檢查！

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

生成SDK。 每個大型API工具都支持生成SDK代碼以訪問API。 檢查！

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

我想指出，任何API工具中最嚴重的缺點都與該工具實現(xiàn)JSON Schema規(guī)范的方式有多徹底。 這并不是說只要API工具完全實現(xiàn)JSON Schema，一切都很棒且完美。 但是，遵循JSON Schema規(guī)范可以避免最嚴重的問題-與解決體系結構上的不可能性相比，我們可以更輕松地解決美學問題。

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

API藍圖缺點

盡管這是一個受歡迎且受到廣泛支持的工具， 但確實可以讓您引用JSON模式來指示請求或響應格式，但它確實難以包含多個文件。 當涉及單一真相來源時（上述清單中的項目1），這就構成了一個主要問題。 如果您的兩個或多個API端點返回相同模式的響應怎么辦？ 如果我們想要一個單一的事實來源，那么所有端點都應該引用同一個文件。

有解決此問題的方法-其他人已記錄了使用API?? Blueprint中的多個文件的方法。 JSON Schema已經支持功能強大的$ref關鍵字，該關鍵字可以充當“ include”語句，因此，如果API Blueprint可以利用此功能，那就太好了。

拉姆

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

我所見過的關于RAML的大多數(shù)抱怨都與其文檔生成的樣式有關（上面列表中的第3項），或者它僅以YAML表示而不具有JSON選項，這兩者都是膚淺的。 其結構與Swagger的差異很小。

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

昂首闊步及其局限性

不論好壞，Swagger都具有吸引人的元素，因此似乎是風在吹拂的地方。 但是，由于缺乏對JSON Schema標準的支持，它確實遭受了一些無用的限制（您猜對了）。

馬上，如果您擁有描述API中所有內容的定義明確且100％有效的JSON Schema文檔，則Swagger將不起作用 。 沒錯：Swagger 2.0僅支持部分 （但不是全部）JSON Schema關鍵字，并且不能保證Open API 3.0（Swagger的下一個迭代）可以解決所有缺點。 實現(xiàn)一些已經存在多年的JSON Schema功能非常困難，更不用說計劃即將發(fā)布的新功能了。

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

讓我們設置一些警告標志，以便您了解一些地雷。 例如，Swagger不允許您的模式聲明其寫入的JSON模式版本。這是使用$schema關鍵字完成的，但是Swagger不支持它。

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

JSON模式的patternProperties關鍵字對于通過正則表達式將值映射到模式非常有用，但是您猜到了，Swagger不支持它。

另一個缺點是它缺乏對模式的“ id”（或“ $ id”）屬性的支持。 用JSON模式的話來說，模式的ID有點像命名空間，因此可以將引用的模式適當?shù)乩斫鉃楦改Ｊ较碌淖幽Ｊ交颡毩⒌亩x。 因此，如果您引用的模式使用$ref指向另一個模式，請當心！ 昂首闊步可能不贊成。 這會使將您的定義分散到多個文件中變得極為困難。 Swagger似乎更喜歡所有可重用的定義都存儲在根文檔的definitions對象中，但這在處理多文件設置時幾乎不可行。

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

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

隨著時間的推移維護您的API定義

無論使用哪種API工具來開發(fā)API，最終都需要對其進行維護。 當您的定義分散在多個文件中時，此任務通常會更容易。 RAML輕松支持這一點，而Swagger可以做一些警告。

請參閱有關將Swagger定義拆分為多個文件的本文 。 在探索過程中，我編寫了一個Github存儲庫，其中包含一些多文件Swagger示例 ，您可能會找到一些有用的參考。

測試您的API

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

摘要

由于Swagger似乎很受歡迎，因此我可能需要花一些時間來考慮RAML或API Blueprint的消失的可能性，但實際上，沒有任何一種解決方案能夠完全實現(xiàn)我作為開發(fā)人員想要的功能（至今）。

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

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

json api

總結

以上是生活随笔為你收集整理的json api_JSON模式在构建和部署API中的作用的全部內容，希望文章能夠幫你解決所遇到的問題。

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