OpenAPI Request Body Example Generation Prompt Template

This prompt is designed for API designers and technical writers who need to generate realistic, schema-conformant example payloads directly from an OpenAPI request body schema. The primary job-to-be-done is eliminating the manual, error-prone work of crafting example JSON or YAML bodies for documentation, mock servers, and SDK tests. The ideal user has a complete or near-complete OpenAPI schema object (the content of a requestBody.content.<media-type>.schema block) and needs multiple examples that cover distinct scenarios: the standard happy path, common edge cases like empty arrays or null fields, and invalid payloads that trigger specific error responses.

You should use this prompt when you have a stable schema and need to accelerate documentation sprints or populate a mock server with realistic data. It is most effective when you provide explicit constraints, such as [CONSTRAINTS] that specify required business rules (e.g., 'date must be in the future' or 'ID must be a UUID'), and a clear [OUTPUT_SCHEMA] that defines the exact wrapper structure for the examples. Do not use this prompt as a substitute for schema design; if your schema is still in flux, the generated examples will inherit that instability. Similarly, avoid using it for schemas with complex, undocumented cross-field validation rules that cannot be expressed in JSON Schema alone—the model will not infer hidden business logic.

Before running this prompt, ensure you have extracted the exact schema object from your OpenAPI spec, including all properties, required fields, enum values, and nested $ref resolutions. The prompt works best when the schema is fully dereferenced and self-contained. After generation, always validate the output against the original schema using a JSON Schema validator and review examples for semantic plausibility. For high-stakes API surfaces, such as payments or healthcare endpoints, a human reviewer must approve every example before it is published or used in a testing harness.

This prompt template generates multiple example payloads for a given OpenAPI request body schema. It is designed to be wired into an API documentation pipeline, a developer portal, or a spec-review tool. The prompt instructs the model to produce examples that cover the happy path, common edge cases, and intentional error scenarios, all while strictly conforming to the provided schema. Use this template when you need to augment an OpenAPI spec with realistic sample data that helps API consumers understand valid and invalid payload shapes before they write a single line of code.

textCopy
You are an API documentation engineer. Your task is to generate realistic, valid example payloads for an OpenAPI request body schema.

## INPUT
- OpenAPI Request Body Schema:
[REQUEST_BODY_SCHEMA]

## CONSTRAINTS
- Generate exactly [NUM_EXAMPLES] examples.
- The first example must be a minimal valid happy-path payload.
- The second example must be a comprehensive payload with all optional fields populated.
- If [NUM_EXAMPLES] is 3 or more, generate additional examples that cover edge cases such as boundary values, empty arrays, null fields where allowed, and invalid enum values.
- Every example must conform to the provided JSON Schema, including required fields, types, formats, enums, min/max constraints, and pattern constraints.
- For any example that intentionally violates the schema, prefix its description with "INVALID: " and explain the violation.
- Use realistic, domain-appropriate values (e.g., real-looking email addresses, UUIDs, timestamps). Do not use placeholder strings like "string" or "foo".

## OUTPUT FORMAT
Return a JSON object with the following structure:
{
  "examples": [
    {
      "description": "A one-sentence description of the scenario this example represents.",
      "payload": { ... }
    }
  ]
}

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

To adapt this template, replace the square-bracket placeholders with concrete values. [REQUEST_BODY_SCHEMA] should contain the raw JSON Schema object from your OpenAPI spec's requestBody.content.<media-type>.schema field. [NUM_EXAMPLES] is an integer, typically 2–5. [FEW_SHOT_EXAMPLES] is optional but strongly recommended for complex or domain-specific schemas; provide 1–2 example input/output pairs that demonstrate the expected style and realism. [RISK_LEVEL] should be set to "high" if the generated examples will be used in production documentation without human review; in that case, add an instruction to flag any schema ambiguities discovered during generation. For high-risk workflows, always run the output through a schema conformance validator before publication. Do not use this prompt for schemas that contain sensitive data patterns unless you have sanitized the schema first.

This prompt is designed to be called programmatically within a documentation generation pipeline, not as a one-off chat interaction. The typical integration point is after an OpenAPI specification has been drafted or updated: for each operation that defines a requestBody, extract the schema, feed it into the prompt, and collect the generated examples. The harness should treat the prompt as a schema-to-examples transformation function with strict input and output contracts. The input is a JSON Schema object (the requestBody.content.<media-type>.schema from the spec), and the output is a structured list of example payloads with metadata about which scenario each example covers.

Input preparation is critical. Before calling the model, extract the relevant schema from the OpenAPI spec and resolve all $ref pointers so the model receives a fully dereferenced schema. Strip any OpenAPI-specific extension properties (like x-* fields) that are not part of the JSON Schema validation vocabulary, as they can confuse the model. If the schema contains oneOf, anyOf, or allOf combinators, consider generating examples for each variant separately by splitting the schema into its constituent branches and calling the prompt once per branch. Output validation must happen in the harness, not in the prompt. After receiving the model's response, parse the JSON and validate every generated example against the original schema using a JSON Schema validator (such as ajv for Node.js or jsonschema for Python). Any example that fails validation should trigger a retry with the validation error message appended to the prompt as additional context, up to a maximum of three retries before flagging the operation for human review.

Model choice matters for this task. Use a model with strong JSON Schema understanding and reliable structured output capabilities. GPT-4o, Claude 3.5 Sonnet, and Gemini 1.5 Pro all perform well, but always enable structured output mode or JSON mode if the provider supports it. For high-volume spec generation, consider batching: collect all request body schemas from a spec, process them in parallel with async calls, and aggregate results. Logging should capture the input schema hash, the model version, the generated examples, validation pass/fail status, and retry count for every operation. This audit trail is essential for debugging when a downstream consumer reports an invalid example. Human review gates should be configured for schemas that fail validation after all retries, schemas with oneOf/anyOf combinators that produce ambiguous examples, and any schema where the model's confidence appears low (detectable by checking if the output includes fewer than the requested number of examples or contains placeholder values like "string").

Integration with the broader docs pipeline requires mapping the generated examples back into the OpenAPI spec. The standard location is under requestBody.content.<media-type>.examples, where each example gets a key (like happy-path, edge-case-minimal, error-invalid-email) and a value containing summary, description, and value fields. Your harness should construct this structure from the model's output and merge it into the spec file. If the spec already contains hand-written examples, configure the harness to either skip those operations or run the prompt in comparison mode, flagging discrepancies between existing examples and schema constraints. Cost control is straightforward: each prompt call processes one schema, so token usage scales with schema complexity, not spec size. For a spec with 50 request body operations and average schema complexity, expect roughly 500-1000 input tokens and 300-800 output tokens per call. Implement caching by hashing the dereferenced schema and skipping generation if the hash matches a previously processed schema, which is common when multiple endpoints share the same request body component.