Configure Multiple Request Body Examples

Apidog supports configuring multiple examples for request bodies of JSON, XML, Raw, and MsgPack type. This feature is useful for:

Configuring examples for different business scenarios: For instance, normal requests vs. exception requests.

Compliance with OAS 3.0/3.1 specifications: Supports exporting standard OpenAPI specifications.

Quickly switching between examples: Useful during debugging and automated tests.

Configuring Multiple Request Body Examples

Apidog version 2.7.0 or later is required.

Create a new request body example

Go to the Edit page of your endpoint documentation.

Locate the Request Body section.

Click the + Add button to create a new request body example.

Configure the request body example

Example Name (optional): If left blank, it will default to Example 1, Example 2, etc.

Example Value (required): Provide the actual example data for the request body.

Description (optional): Add a description to explain the example. Supports Markdown formatting for rich text.

OAS Key (optional): Used when exporting OpenAPI specifications. If not provided, a serial number will be used instead.

OAS Extensions (custom fields): If provided, this will be retained during export.

Save & Use the request body example

Once you've saved the example, it becomes available for use. During debugging, you can easily select from different examples to test your endpoints.

Use request body example during debugging

TIP

For request bodies of Raw type, only the first example value is displayed during debugging.

Extracting Request Parameters as Examples

Extract request parameters as examples

While debugging, if you've manually configured the request body and want to save it as an example, simply click: Extract > Extract to "Request Example".

Choose the Extraction option

You'll be prompted to choose how to save the request parameters:

Overwrite the Example: Replace a previously saved example.

New Example: Save it as a brand-new example.

TIP

The current debugging value will be automatically filled into the example by default.

Use Scenarios

Using Request Body Examples During Debugging

Go to the Run page of the endpoint documentation and locate the Auto-generate section.

Click the dropdown menu to select a request body example. The example will automatically populate.

Switch request body examples during debugging

You can switch between examples in real-time and send requests with the selected example.

Advanced Settings

Click the dropdown icon next to Auto-generate to access the following options:

EXAMPLES: Choose from predefined request body examples.

Generate Each Time: Automatically generate random values based on mock rules.

Auto-generation Preference: For more advanced configurations, refer to Generate Requests.

Documentation Display

For single request body example: Shown in a simplified view without displaying the example name.

For multiple request body examples: Allows switching between examples in a side-by-side layout, displaying example names and Markdown descriptions.

Display Order

The display order for request body examples follows this priority:

Example Name > OAS Key > Serial Number (auto-incremented from 1).

Non-empty items are displayed first.

OAS Compliance

OAS Key

OAS key controls the field names of the examples when exporting OpenAPI specifications.

Configuration: Fill in the OAS Key for the request body examples.

Export Rules:

When filled: The provided OAS key is used as the field name within the object examples.

When not filled: Serial numbers (starting from 1) are automatically used as field names.

When filled

When not filled:

 "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

You can add custom OpenAPI Specification (OAS) extensions to examples.

Configuration: Input JSON key-value pairs in the OAS Extension field.

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

Export Effect: The custom OAS extensions will be fully preserved and included in the exported OpenAPI specifications.

"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`"
    }
}

FAQs

How to Enable Multiple Request Body Examples in Old Projects?

No manual action is required! When you add a second request body example to an existing endpoint, the system automatically upgrades the format to support multiple examples.

How to Handle Multiple Request Body Examples When Exporting OAS?

Will the Order of the Request Body Examples Change in the Exported OAS?

How to Make Exported Example Names More Friendly?

Configure Multiple Request Body Examples

Configuring Multiple Request Body Examples#

Extracting Request Parameters as Examples#

Use Scenarios#

Using Request Body Examples During Debugging#

Documentation Display#

OAS Compliance#

OAS Key#

OAS Extensions#

FAQs#

Configuring Multiple Request Body Examples

Extracting Request Parameters as Examples

Use Scenarios

Using Request Body Examples During Debugging

Documentation Display

OAS Compliance

OAS Key

OAS Extensions

FAQs