Postman 如何使用 JSON Schema

Postman API 平台為 API 生命週期的每個步驟提供了一組豐富的解決方案。多年來，我們親眼目睹了 JSON Schema 如何進入市場，成為描述和註釋 JSON 文件的行業標準。雖然許多替代方案來來去去，但毫無疑問地，JSON Schema 證明了其作為 API 規格運動背後的穩健且可擴展的基礎。根據 Postman 的 2022 年 API 狀態報告，令人印象深刻的 72% 受訪者選擇 JSON Schema 作為他們首選的 API 規格。

由於 JSON Schema 如此深入地融入了當今 API 的開發方式，因此很難在 Postman 組織或 Postman API 平台中找到任何 JSON Schema 沒有以某種方式參與其中的地方。而且隨著 API 優先開發的現代（且日益增長）重要性，API 規格的使用在設計和共享 API 方面起著至關重要的作用。JSON Schema 目前是世界上最流行的 API 規格技術的骨幹，包括 OpenAPI、AsyncAPI 和 RAML。

Postman 組織中的 JSON Schema

Postman 如何使用 JSON Schema 建立自己的 API

Postman 運作著一個複雜的分散式系統，該系統由數十個微服務組成，這些微服務為 Postman API 平台的雲端工具提供動力。這些微服務使用 JSON Schema，透過獨立的 JSON Schema 定義或 OpenAPI 和 AsyncAPI 規格來建立其介面模型。這些微服務中的許多還在底層使用 JSON Schema 來驗證內部資料結構和設定檔，並透過斷言預期的回應或從 JSON Schema 定義自動產生輸入資料來執行端對端測試。作為一家 Node.js 公司，Postman 已開始努力分析如何依靠 TypeScript 註釋從我們的程式碼庫自動產生 OpenAPI 和 AsyncAPI 定義。

鑑於 API 規格對於管理 Postman 的分散式系統的重要性，在 2021 年進行了一項全面的內部研究專案，以了解內部 Postman 平台中運行的微服務引入的多樣化 JSON Schema 定義集。根據可重複使用性、相似程度、唯一性比率和內容類型等特性分析了相應的 JSON Schema 定義。為了提高可重複使用性和可發現性，Postman 正在探索一種新的微服務的想法，該微服務充當中央 JSON Schema 目錄 API。

為了進行分析，Postman 定期從為 Postman API 平台提供動力的每個基於 SQL 的資料庫中提取資料。為了適應我們服務中的結構描述變更，Postman 會在將 SQL 表格定義轉換為 JSON Schema 定義，並將行轉換為 JSON 文件，然後將它們匯總到 Postman 的內部資料倉儲中。已經進行了一些初步實驗，以探索從 JSON Schema 文件中產生 SQL 表格定義，使後者成為事實的來源。

API 以外的 JSON Schema 使用案例

JSON Schema 在 Postman 組織內的使用不僅限於其後端服務。例如，流行的 Postman 集合基於 JSON 的資料格式是使用 JSON Schema 正式定義的。Postman 的 Newman 命令列集合執行器使用 JSON Schema 來驗證自訂報告器的預期輸出。Postman 的內部跨平台桌面框架使用 JSON Schema 來驗證和註釋聲明桌面應用程式各種變體（穩定版、Canary 版等）的設定檔定義。Postman 還維護內部 C4 Postman 架構圖，該架構圖使用 JSON 定義並使用 JSON Schema 驗證。

在 2022 年初，Postman 發布了對 gRPC 和 Protocol Buffers 的支援。在內部，Postman 能夠將 Protocol Buffers 結構描述定義轉換為 JSON Schema 定義，然後再轉換回來。對應於 Protocol Buffers 結構描述的 JSON Schema 定義用於在 gRPC 承載編輯器中提供類型提示和自動完成、驗證使用者輸入以及產生與 Protocol Buffers 結構描述匹配的隨機資料以用於測試目的。這種方法允許 Postman 在單一統一的結構描述語言（JSON Schema）之上實作上述功能。

Postman API 平台中的 JSON Schema

JSON Schema 不僅在內部用於開發 Postman API 平台的各種元件，Postman 提供的許多功能都直接涉及使用 JSON Schema。

Postman 集合環境中的 JSON Schema

Postman 應用程式可用於將 越來越多的 API 規格格式轉換為 Postman 集合。如本文前面所述，最流行的 API 規格格式（如 OpenAPI、Swagger 和 RAML）都依賴於 JSON Schema。在許多情況下，API 規格轉換邏輯需要產生與 JSON Schema 定義匹配的隨機 JSON 文件。

在定義 Postman 集合時，使用者可以定義基於 JavaScript 的測試和預請求腳本，這些腳本在執行相應的集合時會自動執行。嵌入在 Postman 中以執行這些腳本的 JavaScript 引擎與流行的 AJV JSON Schema 驗證器整合。有了它，Postman 使用者可以使用各種 JSON Schema 規格版本編寫採用 JSON Schema 驗證的腳本。

OpenAPI 環境中的 JSON Schema

Postman 應用程式提供了一個豐富的 OpenAPI 編輯器，具有先進的 JSON Schema 功能。該編輯器能夠顯示自動完成和語法警告，並且還會突出顯示 潛在的改進領域，以提高 JSON Schema 和 OpenAPI 端點定義的可讀性和安全性。然後使用 OpenAPI 定義來產生可用端點及其各自 JSON Schema 定義的 豐富的文件，並選擇性地產生以 Go、Java、Python 和 Node.js 撰寫的相符的 伺服器程式碼。

使用 Postman 定義的 API 不僅僅是其 API 定義。它具有周圍的元素，例如文件、測試、模擬伺服器和監控器。在撰寫 OpenAPI 規格時，Postman 會根據 API 規格中包含的 JSON Schema 定義 交叉檢查每個這些元素的完整性。

Postman API 網路

Postman API 平台的一個關鍵組件是 Postman API 網路，它是全球最大的公共 API 註冊中心。這個全球公共註冊中心包含大量的 API 及其對應的 JSON Schema 定義，通常由各自的原始作者維護。一些著名的例子包括Slack Web API、Docker HUB API 和 Twilio API。因此，Postman API 網路是生產級 JSON Schema 定義的最大資料集之一。

Postman 與 JSON Schema

由於 JSON Schema 是 Postman API 平台和 API 生態系統的關鍵組件，Postman 很榮幸能夠支持 JSON Schema 組織，成為 OpenJS 基金會 的一部分，並邀請了一些熱情的核心貢獻者加入 - Ben Hutton、Greg Dennis、Jason Desrosiers 和 Julian Berman - 作為 Postmanauts。我們無法預知未來會發生什麼，但 Postman 確信 API 的未來與 JSON Schema 息息相關。