Example Request and Response Generation Prompt Template

This prompt is designed for documentation engineers and API platform teams who need to generate realistic, valid, and annotated example payloads directly from an OpenAPI specification. The core job-to-be-done is to eliminate the manual, error-prone work of crafting cURL commands, multi-language request snippets, and sample response bodies that accurately reflect the live API contract. The ideal user is someone integrating this prompt into a CI/CD documentation pipeline, where every schema change triggers a regeneration of examples to prevent drift between the docs and the API's actual behavior.

Use this prompt when you have a stable, machine-readable OpenAPI schema and need to produce developer-facing examples at scale. It is particularly effective for REST APIs with well-defined JSON request and response bodies. You should not use this prompt for generating examples from raw code without a spec, for real-time API exploration where a live client is more appropriate, or for APIs that rely heavily on non-JSON payloads like multipart form data or binary streams without explicit schema definitions. The prompt assumes the input schema is the source of truth; it will not question or correct the schema itself.

Before using this prompt, ensure your OpenAPI schema is complete, including examples or example fields where possible, as the model will prioritize these for grounding. The prompt's value is in its ability to generate multiple language variants and annotate the meaning of each field, but it requires a strict evaluation harness to validate that the generated JSON complies with the referenced schema. Do not rely on this prompt for endpoints with complex, stateful business logic where a realistic example depends on a specific sequence of prior API calls; in those cases, supplement the output with a manual 'Setup' note. The next step is to copy the prompt template and wire it into a documentation generation harness that validates output before publication.

This prompt template is designed to be dropped directly into your documentation pipeline. It takes an OpenAPI operation definition and a target language as input, and it produces a complete, annotated example that includes a cURL command, a request body, and a response body. The template uses square-bracket placeholders for all dynamic inputs, making it easy to parameterize in code. Before using this prompt in production, ensure you have a reliable method for extracting the relevant operation object from your OpenAPI spec and for selecting the target language.

codeCopy
You are a senior developer documentation engineer. Your task is to generate a realistic, valid, and well-annotated example for a single API endpoint.

You will be given an OpenAPI operation object and a target programming language. Generate an example that is suitable for inclusion in an API reference page.

### INPUTS
- **Operation Object:** [OPENAPI_OPERATION_OBJECT]
- **Target Language:** [TARGET_LANGUAGE] (e.g., 'curl', 'python', 'javascript')
- **Base URL:** [BASE_URL]

### CONSTRAINTS
- All generated data values must be realistic but clearly synthetic (e.g., use 'acme-corp' instead of 'example-org', 'sk_live_4f8s...' for API keys).
- The request body must strictly validate against the `requestBody` schema in the operation object.
- The response body must strictly validate against the success response schema (typically HTTP 200 or 201) in the operation object.
- Include all required headers, especially `Authorization` and `Content-Type`.
- For the cURL example, use a single-line command with minimal flags for readability.
- For multi-language examples, wrap the code in a fenced code block with the correct language identifier.

### OUTPUT SCHEMA
You must respond with a single JSON object conforming to this structure:
{
  "endpoint_summary": "A one-line description of what the example demonstrates.",
  "curl_example": "A complete, copy-pasteable cURL command.",
  "request_example": {
    "description": "A brief explanation of the request body fields.",
    "code": "The request body in the target language, or as a JSON string if the language is curl."
  },
  "response_example": {
    "description": "A brief explanation of the response body fields and status code.",
    "code": "The response body as a formatted JSON string."
  },
  "notes": ["An array of strings with any important usage notes, such as idempotency key requirements or rate limit headers."]
}

### RISK LEVEL: [RISK_LEVEL]
- If RISK_LEVEL is 'high', add a prominent warning in the notes array that the example should not be used with production credentials.
- If RISK_LEVEL is 'low', you may omit the warning.

To adapt this template, replace the placeholders with data from your source of truth. The [OPENAPI_OPERATION_OBJECT] should be the JSON object for a single path and method (e.g., paths./users.post). The [TARGET_LANGUAGE] drives the format of the request example. The [RISK_LEVEL] flag allows you to conditionally inject safety warnings for destructive operations like DELETE or payment endpoints. After generating the output, always run a programmatic validation step to confirm the generated JSON matches the OUTPUT_SCHEMA and that the request and response bodies validate against their respective schemas. This prevents malformed examples from reaching your documentation site.

The Example Request and Response Generation prompt is designed to be embedded in a documentation generation pipeline, not used as a one-off chat interaction. The typical integration point is after an OpenAPI spec has been parsed and validated, but before the generated examples are published to a developer portal. The harness should accept a resolved OpenAPI schema object (with all $ref pointers dereferenced), an endpoint path, and an HTTP method as inputs. It then constructs the prompt, calls the model, and validates the output before the examples ever reach a docs page.

The implementation must include a schema compliance validator that checks every generated request and response body against the corresponding OpenAPI schema using a JSON Schema validator like ajv. If validation fails, the harness should retry with the validation errors appended to the prompt as [CONSTRAINTS] feedback, up to a configurable retry limit (typically 3 attempts). For multi-language code examples, the harness should also run a syntax check using the target language's parser or linter (e.g., curl --dry-run for cURL examples, python -m py_compile for Python snippets). Log every generation attempt, validation result, and retry count to an observability system so the team can track schema drift or model degradation over time.

For production use, prefer structured output mode (JSON mode or function calling with a defined schema) rather than relying on the model to format code blocks correctly. Define an output schema that includes fields for curl_example, request_body, response_body, response_status, and an array of language_examples with language and code properties. This makes parsing deterministic and allows the harness to extract individual components for different parts of the documentation page. If the endpoint requires authentication, the harness should inject realistic but clearly fake API keys or tokens (e.g., sk-... placeholders) and never use real credentials. For high-risk or regulated APIs, add a human review step before publication, flagging any examples where the model generated potentially confusing or unsafe parameter values.