建立 Schema

使用 Schema 編輯器

Schema 編輯器是一項強大的工具，可協助設計和建模 API 所使用的資料結構。它基於 JSON Schema，並用於設計 JSON 或 XML 資料結構。

使用 Schema 編輯器來：

開發針對特定 API 端點量身打造的 API 請求與回應主體。

建構可套用於一個或多個 API 的資料模型。

每個 schema 都從根物件開始。若要建立 schema，請將屬性新增至此根物件。

新增屬性

點選根物件旁的 +（新增子節點）符號以加入新屬性。

命名您的屬性

輸入屬性的名稱（或 key）。

選擇屬性類型

選擇常見資料類型，或選擇對預先定義 schema 的參照。

進階設定

使用類型編輯器為每個屬性指定資料類型，例如預設值和格式。

管理屬性

透過移動、複製或刪除來重新排列屬性。您也可以為屬性加上描述，並將其標記為必填。

替代方法

您也可以透過從資料庫資料表或 JSON schema 檔案匯入來建立新的 schema。進一步了解從 JSON 等產生 Schema。

屬性類型

依照 JSON Schema 標準，Apidog Schema 編輯器支援以下基本資料類型：

類型	描述
null	表示 JSON 的「null」值。
boolean	表示「true」或「false」值，對應到 JSON 的「true」或「false」值。
object	表示一組無序的鍵值對集合，對應到 JSON 的「object」值。
array	表示一組有序的值列表，對應到 JSON 的「array」值。
number	表示任意精度、以 10 為基數的十進位數值，對應到 JSON 的「number」值。
string	表示 Unicode 字元字串，對應到 JSON 的「string」值。

陣列資料類型

使用 array 資料類型時，系統會自動產生一個子層級的 ITEMS 屬性。它指定陣列中元素的資料類型。

除了前面提到的標準資料結構之外，Apidog Schema 編輯器也支援以下內容：

參照其他 schema：能夠參照並重複使用 API 文件中其他位置定義的 schema。

any：表示可以是任何資料類型的值。

Schema 組合：允許組合多個 schema 以建立複雜資料結構。

自訂：讓使用者能夠自訂並調整 schema，以符合特定需求和資料建模需要。

參照其他 Schema

您可以使用「參照其他 schema」功能來參照先前定義的 schema。

參照另一個 schema 後，您可以在 Schema 編輯器中檢視被參照的 schema。

關於被參照 schema 的重點：

對原始 schema 所做的任何修改，都會反映在參照它的 schema 中。

被參照的 schema 無法直接編輯；若要進行變更，您可以：

點選 schema 名稱以導覽至原始 schema 進行編輯。

在 schema 上點選 Dereference，schema 會轉換成一系列獨立屬性，讓您可以逐一編輯它們。

如果您需要獨立修改特定屬性的定義，可以選擇對該屬性執行 Dereference，以便進行個別修改。對原始 schema 的任何變更都不會影響已解除參照的屬性。

當端點中不需要被參照 schema 的所有屬性時，您可以點選 Hide 來隱藏不必要的屬性。

Schema 組合

如果資料結構中的某個屬性可能有多種資料類型，您可以使用 Schema 組合來組合多個 schema。

Apidog 支援以下組合關鍵字：

關鍵字	描述
allOf (AND)	指定該屬性必須符合組合中定義的所有 schema。
anyOf (OR)	指定該屬性可以符合組合中列出的任一 schema。
oneOf (XOR)	指定該屬性必須且只能符合組合中定義的一個 schema。

選擇 Schema 組合後，屬性下方會出現名為「0」和「1」的子屬性，代表組合中的每個 schema。您可以修改每個子屬性的 schema 類型，並視需要新增其他 schema。

在 API 文件中，Schema 組合會像這樣顯示：

您會注意到 OneOf 下方有兩個可選物件。如果您想要像圖片中那樣顯示它們的名稱，需要在類型編輯器的 title 欄位中輸入名稱。

自訂

選擇「自訂」後，您可以直接在編輯器中編輯 JSON Schema。

屬性設定

每個屬性的資料類型旁都有幾個按鈕：

按鈕	描述
*	表示該屬性是否為必填。
N	指定該屬性是否允許 null 值。
Settings	允許您在類型編輯器中編輯進階設定。

類型編輯器

類型編輯器會以視覺化方式描述符合 JSON Schema 的屬性。

設定好這些進階設定後，它們會在以下區域生效：

新增回應範例時，您可以點選以根據設定自動產生。

它們會顯示在 API 文件中。

在請求主體中，您可以點選以根據設定自動產生。

傳送請求後，回傳的資料會自動依照設定進行驗證。

在模擬服務中，回應資料會根據設定產生。

列舉屬性

對於 String、Integer 和 Number 類型，Apidog 支援 enum。透過切換 enum 開關，您可以新增 enum 值和描述。此外，您也可以對 enum 值執行批次編輯。

模擬

除了屬性中的進階設定外，您也可以透過填入模擬值來指定欄位的模擬內容。模擬值的優先順序高於進階設定中的設定。

模擬值支援 Faker.js 語法，讓您可以直接從下拉選項中選擇所需的 faker 資料。

模擬值也可以輸入為固定值。

XML 設定

對於 XML 資料，Apidog 中的類型編輯器提供額外的 XML 設定。您可以啟用 XML 開關，設定標籤名稱、命名空間等屬性，並預覽對應的 XML 結構。

HashMap、Dictionary、Array

HashMap 也稱為 Map、dictionary 或 associative array。它是鍵值對的集合，其中 key 名稱可以是任何內容，而不是預先定義的。

OpenAPI 規範支援定義具有字串 key 的 HashMap。做法是將元素類型設定為 object，然後使用 additionalProperties 關鍵字來指定鍵值對中值的類型。

假設有一個使用者資訊查詢 API，且回傳資料格式有以下需求：

回傳資料是一個物件

該物件的子元素是 HashMap 的鍵值對

使用者 ID 是 key，使用者資訊是 value

在 Apidog 中定義此結構：

建立新的 schema，並將其命名為「UserProfiles」。

在「UserProfiles」中，將根節點指定為「object」類型。然後點選 Advanced Configuration，將 additionalProperties 設定為 Allow，並點選右側的 Settings 按鈕。

在彈出視窗中，新增所需的使用者資訊，將使用者的姓名和電子郵件作為物件的欄位。它會自動儲存。

在 API 文件的回應中，於根節點參照該 schema，並選擇剛才建立的「user profiles」。

點選儲存，然後您就可以在 API 文件中的回傳回應範例裡看到已定義的 schema 和範例值。

含 additionalProperties 的物件

隨著實際開發工作的迭代，API 回傳的物件相較於原本定義的物件，可能會有 additionalProperties。根據 OpenAPI 規範，這種情況也可以使用 「additionalProperties」 功能處理。

假設現在有一個使用者資訊查詢 API，原本依使用者 ID 查詢使用者資訊時定義的回應欄位是 name 和 email。現在，隨著系統升級，您想要包含其他欄位。

編輯 API 文件時，您可以如下定義：在資料模型的根節點中，點選 Advanced Settings，將 additionalProperties 設定為 Allow，並將欄位值類型設定為 any。

接著您可以在 API 文件中看到已定義的資料結構和範例值。

Tuples

通常，陣列內部的元素必須是相同類型，而 tuples 可以包含不同類型的資料。如果您想定義一個同時包含字串和整數類型的 tuple，例如 (0,"A",2,"C") 這類資料，您可以在資料模型中將元素類型設定為 array，然後在組合模式中將 items 的類型設定為 anyOf，接著分別新增 string 和 integer 類型的子元素。

TIP

如果您想在產生範例時產生多個元素，請在根節點的進階設定中指定元素的最小和最大數量。

儲存後，在 API 文件中點選 Generate Automatically，即可看到已定義的資料結構和範例值。

您也可以在文件的回傳回應中看到 tuple 的範例值。

工具

Apidog 的 Schema 編輯器提供多個非常實用的工具。

工具	描述
Generate from JSON etc.	此工具可讓您從 JSON、XML 資料和其他來源，或直接從資料庫資料表結構，自動產生 schema。進一步了解從 JSON 等產生 schema。
Preview	此工具會建立符合 schema 定義的模擬資料，提供預期資料的預覽。
Generate code	此工具可以產生多種程式語言的資料結構定義程式碼。進一步了解產生程式碼。
JSON Schema	此工具允許直接編輯 JSON schema，以進行微調和自訂。

FAQ

Q：如果字串屬性有多個列舉值，並且用於多個位置，如何在各處一致地參照此 enum？

A：您可以將此屬性定義為由單一屬性組成的獨立 schema，使其能夠在 API 文件的不同部分中被一致參照。

建立 Schema

使用 Schema 編輯器#

建立 Schema#

屬性類型#

參照其他 Schema#

Schema 組合#

自訂#

屬性設定#

類型編輯器#

列舉屬性#

模擬#

XML 設定#

HashMap、Dictionary、Array#

含 additionalProperties 的物件#

Tuples#

工具#

FAQ#

使用 Schema 編輯器

建立 Schema

屬性類型

參照其他 Schema

Schema 組合

自訂

屬性設定

類型編輯器

列舉屬性

模擬

XML 設定

HashMap、Dictionary、Array

含 additionalProperties 的物件

Tuples

工具

FAQ