配置多个请求主体示例

Apidog 支持为 JSON、XML、Raw 和 MsgPack 类型的请求主体配置多个示例。此功能适用于：

为不同业务场景配置示例：例如，正常请求与异常请求。

符合 OAS 3.0/3.1 规范：支持导出标准 OpenAPI 规范。

在示例之间快速切换：适用于调试和自动化测试期间。

配置多个请求主体示例

需要 Apidog 版本 2.7.0 或更高版本。

创建新的请求主体示例

前往端点文档的 Edit 页面。

找到 Request Body 部分。

点击 + Add 按钮创建新的请求主体示例。

配置请求主体示例

Example Name（可选）：如果留空，将默认使用 Example 1、Example 2 等。

Example Value（必填）：提供请求主体的实际示例数据。

Description（可选）：添加描述以说明该示例。支持 Markdown 格式的富文本。

OAS Key（可选）：导出 OpenAPI 规范时使用。如果未提供，将改用序列号。

OAS Extensions（自定义字段）：如果提供，将在导出期间保留。

保存并使用请求主体示例

保存示例后，即可使用它。在调试期间，你可以轻松从不同示例中进行选择，以测试你的端点。

TIP

对于 Raw 类型的请求主体，调试期间仅显示第一个示例值。

将请求参数提取为示例

调试时，如果你已手动配置请求主体并希望将其保存为示例，只需点击：Extract > Extract to "Request Example"。

选择提取选项

系统会提示你选择如何保存请求参数：

Overwrite the Example：替换之前保存的示例。

New Example：将其保存为全新示例。

TIP

当前调试值默认会自动填入示例中。

使用场景

调试期间使用请求主体示例

前往端点文档的 Run 页面，并找到 Auto-generate 部分。

点击下拉菜单以选择请求主体示例。示例将自动填充。

你可以实时在示例之间切换，并使用所选示例发送请求。

高级设置

点击 Auto-generate 旁边的下拉图标以访问以下选项：

EXAMPLES：从预定义的请求主体示例中选择。

Generate Each Time：根据 mock rules 自动生成随机值。

Auto-generation Preference：如需更高级的配置，请参阅 Generate Requests。

文档展示

对于单个请求主体示例：以简化视图显示，不显示示例名称。

对于多个请求主体示例：允许在并排布局中切换示例，显示示例名称和 Markdown 描述。

显示顺序

请求主体示例的显示顺序遵循以下优先级：

Example Name > OAS Key > 序列号（从 1 开始自动递增）。

非空项目优先显示。

OAS 合规性

OAS Key

OAS key 用于控制导出 OpenAPI 规范时示例的字段名称。

配置：为请求主体示例填写 OAS Key。

导出规则：

填写时：提供的 OAS key 将用作对象 examples 中的字段名称。

未填写时：系统会自动使用序列号（从 1 开始）作为字段名称。

填写时

未填写时：

 "examples": {
   "example1": {
      "value": {
        "name": "Blake Keeling",
        "id": "165061",
        "email": "Blake.Keeling@gmail.com"
      },
      "summary": "example1",
      "description": "This is`example 1`"
    },
    "example2": {
       "value": {
        "name": "Jolie Kutch",
        "id": "138164",
        "email": "Jolie_Kutch@hotmail.com"
      },
      "summary": "example 2",
      "description": "This is`example 2`"
    }
  }

"examples": {
   "1": {
     "value": {
       "name": "Blake Keeling",
       "id": "165061",
       "email": "Blake.Keeling@gmail.com"
     },
     "summary": "example1",
     "description": "This is`example 1`"
   },
    "2": {
      "value": {
       "name": "Jolie Kutch",
       "id": "138164",
       "email": "Jolie_Kutch@hotmail.com"
     },
     "summary": "example 2",
     "description": "This is`example 2`"
   }
 }

OAS Extensions

你可以向示例添加自定义 OpenAPI Specification（OAS）扩展。

配置：在 OAS Extension 字段中输入 JSON 键值对。

{
  "x-demo": true,
  "x-scenario": "error_case"
}

导出效果：自定义 OAS 扩展将被完整保留，并包含在导出的 OpenAPI 规范中。

"examples": {
    "example1": {
      "x-demo": true,
      "x-scenario": "error_case",
      "value": {
         "name": "Blake Keeling",
         "id": "165061",
         "email": "Blake.Keeling@gmail.com"
      },
      "summary": "example1",
      "description": "This is`example 1`"
    }
}

常见问题

如何在旧项目中启用多个请求主体示例？

无需手动操作！当你向现有端点添加第二个请求主体示例时，系统会自动升级格式以支持多个示例。

导出 OAS 时如何处理多个请求主体示例？

导出的 OAS 中请求主体示例的顺序会改变吗？

如何让导出的示例名称更友好？

配置多个请求主体示例

配置多个请求主体示例#

将请求参数提取为示例#

使用场景#

调试期间使用请求主体示例#

文档展示#

OAS 合规性#

OAS Key#

OAS Extensions#

常见问题#

配置多个请求主体示例

将请求参数提取为示例

使用场景

调试期间使用请求主体示例

文档展示

OAS 合规性

OAS Key

OAS Extensions

常见问题