构建 Schema

使用 Schema Editor

Schema Editor 是一个强大的工具，可帮助你设计和建模 API 所使用的数据结构。它基于 JSON Schema，用于设计 JSON 或 XML 数据结构。

使用 Schema Editor 可以：

为特定 API 端点开发 API 请求和响应主体。

构建可应用于一个或多个 API 的数据模型。

每个 schema 都从一个根对象开始。要构建 schema，请向此根对象添加属性。

添加属性

点击根对象旁边的 +（添加子节点）标志以引入新属性。

命名你的属性

输入属性的名称（或键）。

选择属性类型

选择常见数据类型，或选择对预定义 schema 的引用。

高级设置

使用 Type Editor 为每个属性分配数据类型，例如默认值和格式。

管理属性

通过移动、复制或删除属性来重新排列它们。你还可以为属性添加描述，并将其标记为必填。

替代方法

你也可以通过从数据库表或 JSON schema 文件导入来创建新的 schema。了解更多关于 Generate Schemas from JSON etc. 的信息。

属性类型

根据 JSON Schema 标准，Apidog Schema Editor 支持以下基本数据类型：

类型	描述
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 Editor 还支持以下内容：

引用其他 schema：能够引用并复用 API 文档中其他位置定义的 schema。

any：表示可以是任何数据类型的值。

Schema Composition：允许组合多个 schema 以创建复杂的数据结构。

自定义：使用户能够自定义和调整 schema，以满足特定需求和数据建模需要。

引用其他 Schema

你可以使用“引用其他 schema”功能来引用先前定义的 schema。

引用另一个 schema 后，你可以在 Schema Editor 中查看被引用的 schema。

关于被引用 schema 的要点：

对原始 schema 所做的任何修改都会反映到引用它的 schema 中。

被引用的 schema 不能直接编辑；如需进行更改，你可以：

点击 schema 名称以跳转到原始 schema 进行编辑。

通过点击 schema 上的 Dereference，该 schema 将转换为一系列独立属性，使你可以逐个编辑它们。

如果需要独立修改某个特定属性的定义，可以选择对该属性执行 Dereference，以便进行单独修改。对原始 schema 的任何更改都不会影响已解除引用的属性。

如果端点中不需要被引用 schema 的所有属性，可以点击 Hide 来隐藏不必要的属性。

Schema Composition

如果数据结构中的某个属性可能有多种数据类型，你可以使用 Schema Composition 来组合多个 schema。

Apidog 支持以下组合关键字：

关键字	描述
allOf (AND)	指定该属性必须符合组合中定义的所有 schema。
anyOf (OR)	指定该属性可以符合组合中列出的任意 schema。
oneOf (XOR)	指定该属性必须且只能符合组合中定义的一个 schema。

选择 Schema Composition 后，属性下会出现名为 “0” 和 “1” 的子属性，分别表示组合中的每个 schema。你可以修改每个子属性的 schema 类型，并根据需要添加更多 schema。

在 API 文档中，Schema Composition 将显示如下：

你会注意到 OneOf 下的两个可选对象。如果想要像图片中那样显示它们的名称，需要在 Type editor 的 title 字段中输入名称。

自定义

通过选择“Customize”，你可以在编辑器中直接编辑 JSON Schema。

属性设置

对于每个属性，数据类型旁边都有几个按钮：

按钮	描述
*	表示该属性是否为必填。
N	指定该属性是否允许 null 值。
Settings	允许你在 Type Editor 中编辑高级设置。

Type Editor

Type Editor 以可视化方式描述属性，并与 JSON Schema 保持一致。

配置这些高级设置后，它们将在以下区域生效：

添加响应示例时，你可以点击根据设置自动生成。

它们将显示在 API 文档中。

在请求主体中，你可以点击根据设置自动生成。

发送请求后，返回的数据将根据这些设置自动进行校验。

在模拟服务中，响应数据将根据这些设置生成。

枚举属性

对于 String、Integer 和 Number 类型，Apidog 支持 enum。通过开启 enum 开关，你可以添加枚举值和描述。此外，你还可以对枚举值执行 Bulk Edit。

模拟

除了属性中的高级设置外，你还可以通过填写模拟值来为字段指定模拟内容。模拟值优先于高级设置中的设置。

模拟值支持 Faker.js 语法，允许你直接从下拉选项中选择所需的 faker 数据。

模拟值也可以作为固定值输入。

XML 设置

对于 XML 数据，Apidog 中的 Type Editor 提供额外的 XML 设置。你可以启用 XML 开关，配置标签名称、命名空间等属性，并预览相应的 XML 结构。

HashMap、字典、数组

HashMap 也称为 Map、字典或关联数组。它是键值对的集合，其中键名可以是任何内容，而不是预先定义的。

OpenAPI 规范支持定义带字符串键的 HashMap。这是通过将元素类型设置为 object，然后使用 additionalProperties 关键字来指定键值对中值的类型来实现的。

假设有一个用户信息查询 API，返回的数据格式有以下要求：

返回的数据是一个对象

对象的子元素是 HashMap 的键值对

用户 ID 是键，用户信息是值

在 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 文档中看到已定义的数据结构和示例值。

元组

通常，数组的内部元素必须是相同类型，而元组可以包含不同类型的数据。如果你想定义一个同时包含字符串和整数类型的元组，例如 (0,"A",2,"C") 这样的数据，可以在数据模型中将元素类型设置为 array，然后在组合模式中将 items 的类型设置为 anyOf，再分别添加 string 和 integer 类型的子元素。

TIP

如果在生成示例时想要生成多个元素，请在根节点的高级设置中指定元素的最小数量和最大数量。

保存后，在 API 文档中点击 Generate Automatically，即可看到已定义的数据结构和示例值。

你还可以在文档的返回响应中看到元组的示例值。

工具

Apidog 中的 Schema Editor 提供了几个非常有用的工具。

工具	描述
Generate from JSON etc.	此工具允许你从 JSON、XML 数据和其他来源自动生成 schema，或直接从数据库表结构生成。了解更多关于 Generate schemas from JSON etc. 的信息。
Preview	此工具会创建符合 schema 定义的模拟数据，提供对预期数据的预览。
Generate code	此工具可以生成各种编程语言的数据结构定义代码。了解更多关于 Generate code 的信息。
JSON Schema	此工具允许直接编辑 JSON schema，以便进行微调和自定义。

FAQ

Q：如果一个字符串属性有多个枚举值，并在多个位置使用，如何在各处一致地引用此 enum？

A：你可以将此属性定义为由单个属性组成的独立 schema，从而使其能够在 API 文档的不同部分被一致引用。

构建 Schema

使用 Schema Editor#

构建 Schema#

属性类型#

引用其他 Schema#

Schema Composition#

自定义#

属性设置#

Type Editor#

枚举属性#

模拟#

XML 设置#

HashMap、字典、数组#

带有 additionalProperties 的对象#

元组#

工具#

FAQ#

使用 Schema Editor

构建 Schema

属性类型

引用其他 Schema

Schema Composition

自定义

属性设置

Type Editor

枚举属性

模拟

XML 设置

HashMap、字典、数组

带有 additionalProperties 的对象

元组

工具

FAQ