构建数据模型

编辑数据模型

数据模型提供了一个直观的可视化编辑界面，是一个功能强大的工具组件，专为设计和构建 API 数据结构而打造。基于 JSON Schema，可用于创建 JSON 或 XML 数据结构。

每个数据模型以一个根对象为起点。构建数据模型时，需要向该根对象添加参数。

构建数据模型的步骤：

添加参数

点击根对象旁边的 +（添加子节点）图标，引入新参数。

命名参数

输入参数的名称（或键）。

选择参数类型

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

高级设置

为每个参数分配数据类型，例如默认值和格式。

管理参数

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

你也可以通过从数据库表或导入 JSON Schema 文件来创建新的数据模型。了解更多关于通过 JSON 等生成的信息。

参数类型

基于 JSON Schema 标准，Apifox 的数据模型编辑组件支持以下基本数据类型：

null：表示 JSON 中的 null 值。

boolean：表示布尔值，对应 JSON 中的 true 或 false。

object：表示键值对的无序集合，对应 JSON 中的 object 类型。

array：表示有序的值列表，对应 JSON 中的 array 类型。

使用 array 数据类型时，将自动生成一个子级 ITEMS 属性。它指定数组内元素的数据类型。

number：表示任意精度的十进制数值，对应 JSON 中的 number 类型。

string：表示由 Unicode 字符组成的字符串，对应 JSON 中的 string 类型。

除了上述标准数据类型外，Apifox 数据模型编辑组件还支持以下功能：

引用其他数据模型：可以引用并复用 API 文档中已定义的其他数据模型。

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

数据模型组合：支持将多个数据模型组合在一起，以构建复杂的数据结构。

自定义：允许用户根据特定需求自定义和调整数据模型。

引用其他数据模型

你可以通过 “引用其他数据模型” 功能，引用之前定义的数据模型。

在引用其他数据模型后，你可以在数据模型编辑组件中查看已引用的数据模型。

对原始数据模型的任何修改将自动反映在引用的数据模型中。

引用的数据模型无法直接编辑；若需修改，可采取以下方式：

点击数据模型名称，导航至原始数据模型进行编辑。

点击 解除关联，该数据模型将转化为一组独立的属性，允许单独编辑。

若只需修改特定属性的定义，可选择 解除关联 该属性，以便进行单独调整。此时，原始数据模型的任何更改将不会影响已取消引用的属性。

在引用的数据模型中，如果某些参数在接口中并非必填，可以通过点击 隐藏字段 来禁用不必要的参数。

数据模型组合

如果数据结构中的某个参数可以具有多种数据类型，可以使用组合模式将多个数据模型进行组合。

Apifox 支持以下组合关键字：

allOf (AND)：指定该参数必须符合组合中定义的所有数据模型。

anyOf (OR)：指定该参数可以符合组合中列出的任意数据模型。

oneOf (XOR)：指定该参数必须符合组合中定义的一个且仅一个数据模型。

选择组合模式后，名为“0”和“1”的子参数将显示在该参数下，分别表示组合中的每个数据模型。你可以修改每个子参数的数据模型类型，并根据需要添加其他数据模型。

在 API 文档中，数据模型组合将显示如下：

自定义

选择 “自定义” 后，可以在编辑组件中直接编辑 JSON Schema。

参数设置

对于每个参数字段，数据类型旁边有几个按钮：

*：指示该参数是否为必填。

N：指定该参数是否允许 null 值。

设置：允许你在类型编辑器中编辑高级设置。

类型编辑器

类型编辑器以可视化方式描述一个参数，符合 JSON Schema 标准。

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

在添加响应示例时，可以点击 “自动生成”，根据配置规则生成示例数据。

配置将在 API 文档中展示。

在请求 Body 中，可以点击 “自动生成”，基于配置规则生成请求数据。

发送请求时，返回的数据将自动根据配置规则进行验证。

在 Mock 服务中，响应数据将根据配置规则生成。

枚举

对于 String、Integer 和 Number 类型，Apifox 支持枚举功能。通过启用枚举开关，你可以添加枚举值及其描述，并支持对枚举值进行批量编辑。

Mock

除了参数中的高级设置外，你还可以通过为字段指定 Mock 值来填充 Mock 内容。Mock 值优先于高级设置中的配置规则。

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

Mock 值也可以作为固定值进行输入。

XML 设置

对于 XML 数据，Apifox 的类型编辑器提供了额外的 XML 设置。你可以启用 XML 开关，配置标签名、命名空间等属性，并预览生成的 XML 结构。

其他功能组件

Apifox 中的数据模型编辑组件提供了几个非常有用的功能。

从 JSON 等生成：此功能允许你从 JSON、XML 数据及其他来源自动生成数据模型，或直接根据数据库表结构生成。了解更多关于通过 JSON 等生成的信息。

预览：该功能可生成符合数据模型定义的 Mock 数据，帮助你预览预期的数据结构。

生成代码：此功能可以生成多种编程语言中的数据结构定义代码。了解更多关于生成代码的信息。

JSON Schema：此功能允许你直接编辑 JSON 数据模型，便于进行微调和自定义。

常见问题

如果一个参数有多个枚举值，并在多个位置使用，如何保持枚举的一致性引用？

你可以将该参数定义为一个独立的数据模型，包含一个参数字段，从而在 API 文档的不同部分中保持一致的引用。

编辑数据模型#

参数类型#

引用其他数据模型#

数据模型组合#

自定义#

参数设置#

类型编辑器#

枚举#

Mock#

XML 设置#

其他功能组件#

常见问题#

编辑数据模型

参数类型

引用其他数据模型

数据模型组合

自定义

参数设置

类型编辑器

枚举

Mock

XML 设置

其他功能组件

常见问题