API Contract Generation Demonstration Prompt

This prompt is for integration engineers and AI developers who need to generate a valid OpenAPI or GraphQL schema from a set of example request-response pairs. The core job-to-be-done is teaching a model to infer a strict, typed API contract by observing concrete HTTP interactions, rather than relying on verbose natural-language instructions. This is the right tool when you have a collection of raw API traffic, curl commands, or log excerpts and you need a machine-readable specification that downstream tools, code generators, and validators can consume without manual cleanup.

Use this prompt when the desired output is a structural specification, not a prose description. It is ideal for reverse-engineering internal or third-party APIs where documentation is missing, stale, or non-existent. The required context includes a set of at least 3-5 diverse example interactions covering different endpoints, HTTP methods, success and error responses, and authentication headers. The prompt is designed to work with a few-shot demonstration pattern, where you provide formatted input-output pairs that explicitly model endpoint discovery, parameter typing, error response modeling, and authentication annotation. Do not use this prompt for generating API client code, writing prose documentation, or designing a new API from scratch—it infers a contract from existing traffic, it does not architect a greenfield API.

Before wiring this into a production pipeline, validate the generated schema against the OpenAPI or GraphQL specification using a standard linter like spectral or graphql-inspector. The prompt includes a harness for schema conformance checks, but you must add a human review step if the generated contract will be used to enforce request validation, generate SDKs, or configure an API gateway. The most common failure mode is the model hallucinating optional fields or endpoints not present in the provided examples; always diff the generated contract against the source traffic to catch additions. Proceed by collecting your example pairs, formatting them according to the demonstration structure, and running the prompt with a strict output schema constraint.

This prompt template teaches a model to generate an OpenAPI 3.0 specification from a set of example HTTP request-response pairs. It uses few-shot demonstrations to show the model how to infer endpoint paths, parameter types, request bodies, response schemas, error codes, and authentication annotations. The template is designed for integration engineers who need a starting point that can be adapted to their own API surface and documentation standards.

textCopy
You are an API specification generator. Given example HTTP request-response pairs, produce a valid OpenAPI 3.0 YAML specification.

Follow these rules:
- Infer the base URL, endpoint paths, HTTP methods, and parameter locations from the examples.
- For each endpoint, define request parameters (path, query, header, cookie) with types, required flags, and descriptions.
- Define request bodies with JSON Schema for content types present in the examples.
- Define response schemas for each status code observed, including error responses.
- Add authentication annotations (e.g., bearerAuth, apiKey) if headers like Authorization or X-API-Key appear.
- Use consistent naming: camelCase for properties, kebab-case for paths.
- Include operationId, summary, and description fields for every operation.
- If an example is ambiguous, mark the inferred field with a comment: # INFERRED: <reason>.
- Output ONLY the YAML specification, no surrounding explanation.

[EXAMPLES]

[INPUT]

[OUTPUT_SCHEMA]

[CONSTRAINTS]

To adapt this template, replace [EXAMPLES] with 2-4 annotated demonstration pairs showing raw HTTP traffic and the corresponding OpenAPI fragment. Replace [INPUT] with the new request-response pairs to process. Use [OUTPUT_SCHEMA] to specify the expected top-level OpenAPI structure (e.g., openapi: 3.0.0, info, servers, paths, components). Use [CONSTRAINTS] to add domain-specific rules such as required error codes, naming conventions, or security scheme types. After generation, validate the output against the OpenAPI 3.0 specification using a schema validator. For production use, add a human review step to confirm inferred types, required fields, and authentication annotations before publishing the contract.

The API Contract Generation Demonstration Prompt is designed to be embedded in a pipeline that takes raw request-response pairs and produces a validated OpenAPI or GraphQL schema. This is not a one-shot chat interaction—it's a structured generation step that must be followed by automated validation, repair loops, and human review for production use. The prompt's few-shot demonstrations teach the model to discover endpoints, infer parameter types, model error responses, and annotate authentication requirements, but the output must be treated as a draft that requires mechanical verification before it touches any downstream system.

Wire the prompt into an application by first assembling the input context: a set of example request-response pairs, any known base URLs, and the target specification format (OpenAPI 3.1 or GraphQL SDL). Pass these into the prompt template using the [INPUT_EXAMPLES], [BASE_URL], and [SPEC_FORMAT] placeholders. After generation, run the output through a spec validator—openapi-spec-validator for OpenAPI or graphql npm package for SDL—to catch structural errors immediately. If validation fails, feed the error messages back into a repair prompt (see the Few-Shot JSON Repair Demonstration Prompt in this pillar) with a maximum of two retry attempts. Log every generation attempt, validation result, and repair step for observability. For high-risk integrations where the generated contract will be used to generate client SDKs or enforce API gateways, require human review of endpoint paths, parameter types, and authentication scopes before acceptance.

Model choice matters here. Use a model with strong structured output capabilities and a context window large enough to hold your example pairs plus the prompt. For OpenAPI generation, prefer models that have been fine-tuned on code and schema tasks. Set temperature low (0.0–0.2) to reduce creative drift in field names and type inference. If your examples include sensitive request bodies or authentication tokens, strip those before they enter the prompt—this prompt should work with sanitized shape-only examples. The next step after implementing this harness is to build a regression test suite using known request-response pairs and their expected schema outputs, so you can detect when model updates or prompt changes silently degrade contract quality.