Apidog supports adding multiple request body examples for each endpoint, making your API documentation more helpful and compatible with OpenAPI specifications. This feature lets you show different ways to structure requests for the same endpoint, which helps developers understand how to use your API in various situations.
Request body examples are useful because they:
- Show developers exactly how to format their requests
- Demonstrate different use cases for the same endpoint
- Make testing easier by providing ready-to-use request structures
- Ensure your documentation follows OpenAPI standards
You can add as many as you need to cover all possible scenarios.
Step-by-Step: Adding Your First Request Body Example
Adding request body examples in Apidog is straightforward. Here's how to get started:
1. Open your API project in Apidog (version 2.7.0 or higher)
2. Navigate to the endpoint where you want to add examples
3. Click the "Edit" tab to access the documentation editor and Scroll to the "Request Body" section
4. Click on the "Add Exampe" to create a new example
5. Fill in the example details:
- Example Name: Give your example a clear name (e.g., "Standard Request")
- Example Value: Enter the actual JSON, XML, or other formatted data
- Description: Explain when to use this example (supports Markdown)
- OAS Key: Provide an identifier for OpenAPI export (optional but recommended)
- OAS Extensions: Add any custom fields needed for export (optional)
6. Click "Save" to create the example
The example name helps users identify the purpose of each example. If you leave it blank, Apidog will automatically name it "Example 1," "Example 2," etc.
The example value should show a valid request structure. For JSON content types, Apidog provides a structured editor to help ensure valid formatting.
The description field is where you can explain when and why someone would use this particular request structure. Using Markdown here can make your explanations clearer.
The OAS Key is important if you plan to export your documentation to OpenAPI format. This key becomes the identifier for the example in the exported specification.
Creating Multiple Examples for Different Scenarios
After adding your first example, you'll want to create additional examples for different use cases:
- Click the "+ Add" button again to create another example
- Give it a distinct name that clearly identifies the scenario (e.g., "Minimal Request")
- Enter the example value for this specific scenario
- Add a detailed description explaining when to use this example
- Configure the OAS Key and Extensions as needed
- Click "Save" to add the example
- Repeat this process for all relevant scenarios
When creating multiple examples, consider covering these common scenarios:
- Standard Request: The typical way to use the endpoint
- Minimal Request: The simplest valid request structure
- Complete Request: A request using all possible fields
- Special Case: Examples for unique business scenarios
Each example should show a different way to use the endpoint. This helps developers understand the full range of possibilities when working with your API.
Apidog displays examples in a specific order:
- Examples with names come before unnamed examples
- Examples with OAS Keys are shown before those without
- Examples without names or OAS Keys are ordered by their serial numbers
To make your most important examples appear first, give them clear names and OAS Keys.
Using Request Body Examples for Testing
One of the best features of multiple request body examples is how they simplify testing:
- Navigate to the "Run" page of your endpoint
- Find the "Auto-generate" section in the request configuration
- Click the dropdown menu to see all available examples
- Select the example you want to test
- The request body will be automatically filled with the selected example
- Click "Send" to test the endpoint with this example
This makes it easy to test different scenarios without having to manually type or paste different request structures. You can quickly switch between examples to see how your API handles various inputs.
Apidog also lets you create examples from your testing sessions:
- Configure a request body in the "Run" page
- Click the "Extract" button
- Select "Extract to Request Example"
- Choose to create a new example or update an existing one
- Your current request body will be saved as an example
This is helpful when you've found a working request structure during testing and want to save it for future reference or documentation.
Ensuring OpenAPI Compatibility with Your Examples
Apidog's request body examples are designed to work seamlessly with OpenAPI specifications. When you export your API documentation, all your examples are properly formatted according to OAS 3.0/3.1 standards.
Here's how examples are handled during export:
- Each example is included in the exported specification
- Example names come from the OAS Key if provided (or serial numbers if not)
- Example descriptions are preserved in the exported format
- Any custom OAS Extensions are included in the export
The exported OpenAPI specification will include your examples in a structure like this:
"examples": {
"standard_request": {
"value": {
"name": "John Doe",
"id": "12345",
"email": "john.doe@example.com"
},
"summary": "Standard Request",
"description": "This is a standard request with all required fields."
},
"minimal_request": {
"value": {
"id": "12345"
},
"summary": "Minimal Request",
"description": "This is a minimal request with only the required ID field."
}
}
To ensure the best compatibility with OpenAPI:
- Use meaningful OAS Keys for all examples
- Provide clear descriptions that explain each example's purpose
- Review your exported specifications to verify everything looks correct
This ensures that your examples remain valuable not just within Apidog but also when shared through OpenAPI specifications.
Best Practices for Request Body Examples
To get the most value from multiple request body examples, follow these best practices:
Create Comprehensive Example Sets
Include examples that cover:
- Basic usage with just the required fields
- Typical usage with commonly used optional fields
- Complete usage showing all possible fields
- Edge cases that demonstrate special situations
Use Clear Naming
- Give each example a descriptive name that indicates its purpose
- Use consistent naming patterns across different endpoints
- Avoid generic names like "Example 1" that don't explain the content
Write Helpful Descriptions
- Explain when and why someone would use each example
- Mention any special considerations for this request structure
- Use Markdown formatting to make descriptions easier to read
- Include expected responses when relevant
Organize Examples Logically
- Put the most common scenarios first
- Group related examples together
- Remove outdated examples to avoid confusion
- Update examples when your API changes
Use OAS Keys Effectively
- Choose meaningful keys that describe the example's purpose
- Use consistent key naming across your API
- Avoid special characters that might cause issues in exports
By following these practices, you'll create request body examples that truly help developers understand and use your API effectively.
Conclusion
Adding multiple request body examples in Apidog is a simple yet powerful way to improve your API documentation. By showing different ways to structure requests for the same endpoint, you help developers understand how to use your API in various situations.
The step-by-step process is straightforward:
- Navigate to your endpoint and click "Edit"
- Scroll to the Request Body section and click "+ Add"
- Configure your example with a name, value, description, and OAS Key
- Repeat for additional scenarios
- Use your examples for testing and documentation
With proper examples in place, your API becomes easier to understand, test, and implement. This leads to faster adoption, fewer support questions, and a better developer experience overall.
Start adding multiple request body examples to your Apidog documentation today to see the benefits for yourself and your API users.
