OpenAPI prompts help when an HTTP interface description and its implementation have started to diverge. A document might describe the success response while omitting the errors a client actually handles. Another might accept an example that contradicts its own schema. This collection turns those gaps into review tasks: clarifying one operation, comparing a contract change and deriving tests that check the description against running behavior.
Start with the exact document and toolchain
Provide the OpenAPI file, declared specification version and the validator or generator your project uses. Include a route handler and a sanitized response for the operation under review. If the contract is generated, explain which file is the source. Editing generated output alone can create a correction that disappears on the next build.
The OpenAPI 3.1.1 specification is a versioned reference for HTTP interface descriptions. It is cited here as a concrete reference, not as a claim that every project should use that version. Have the agent consult the edition supported by your toolchain before changing schema syntax.
Fill gaps in one operation
A useful contract review connects each field to observed behavior or an explicit requirement. Ask the agent to label inference separately from verified implementation. This matters for authentication failures, pagination and validation errors, where route helpers may add behavior outside the main handler. A complete-looking file with invented examples can be harder to fix than a short list of acknowledged gaps.
Review {{operation_id}} in {{openapi_file}} against {{route_files}}.
Check parameters, request bodies, authentication, response codes, error
schemas and examples. Mark every proposed field as implementation-backed,
requirement-backed or unresolved. Preserve our declared OpenAPI version.
Run {{validator_command}} if available and list remaining contract gaps.
Compare changes from a consumer's perspective
A field that becomes required can break an existing caller even when no path changes. So can a narrower allowed value or a different error representation. Ask for concrete requests or responses that worked before and would fail after the change. Include consumer evidence rather than relying only on a structural diff.
Compare {{old_contract}} and {{new_contract}} for {{known_consumers}}.
List potentially breaking input, output, authentication and error changes.
For each finding, give an old valid request or consumer assumption that
would stop working. Distinguish confirmed breaks from uncertain ones.
Propose a migration path and validation checks without silently changing
the intended API behavior.
Derive tests that check real behavior
Examples in a description are useful fixtures, but checking only those examples can miss an implementation that rejects valid alternatives. Ask for boundary and negative cases that follow the documented rules. Make schema checks complement behavioral assertions: a structurally valid response may still belong to the wrong user or represent the wrong state.
Create contract-focused tests for {{operation_id}} using {{test_tool}}.
Read {{openapi_file}} and our existing API tests. Cover documented success,
validation failure and {{authorization_case}}. Add boundary inputs based
on declared constraints. Verify both schema shape and meaningful behavior.
Report any implementation-description mismatch before choosing which side
to change, and never invent undocumented status codes as established fact.
Keep a traceable contract workflow
Review changes with the generated client or documentation build your team actually ships. Confirm examples validate and references resolve in that environment. Record the exact validator invocation and any unsupported constructs so a future upgrade does not erase an important compatibility constraint.
Save the reviewed OpenAPI prompt in Kipt with blanks for operation, version and consumer evidence. For a broader behavior suite, use the API testing prompts; for graph-based operations, see the GraphQL prompts.