OpenAPI and Swagger Contract Workflow

Pathrule2 Rules • 2 Memories • 1 Skill

An OpenAPI document becomes harmful when it describes a different API than production, accepts broad unspecified objects, changes response or error semantics without detection, or generates clients from an unpublished local schema. This pattern constrains contract authority and compatibility while recording schema reuse and generated-artifact ownership and providing a release verification procedure. It complements REST API design by governing specification lifecycle, validation, diffing, documentation, and code generation rather than resource and HTTP semantics themselves.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

release-openapi-contract

openapi/

Choose one authoritative contract generation direction

Compatibility is evaluated from the consumer's view

Examples are executable contract fixtures

src/

api/

Validate runtime traffic against the public schema

Rules

Choose one authoritative contract generation direction/openapihighstrictMake the reviewed OpenAPI artifact derive code or derive from code through one reproducible pipeline, never through manual edits on both sides.

1	When annotations, handlers, and YAML can each be edited independently, drift has no deterministic resolution. The team needs one source and a build that reproduces the published artifact.
2
3	- Declare contract-first or code-first ownership and identify the files reviewers change for paths, schemas, security, errors, and examples.
4	- Generate the distributable schema in CI from a clean checkout and fail when committed or published output differs.
5	- Do not patch generated clients or schema output manually; change the source and regenerate.
6	- Version and publish the exact schema used for server validation, documentation, gateway configuration, and client generation.
7
8	See /generated for the adjacent decision or procedure that completes this constraint.

Validate runtime traffic against the public schema/src/apihighstrictParse request boundaries and verify representative responses so TypeScript, annotations, and implementation cannot silently diverge.

1	A static contract diff proves only document compatibility. Runtime serializers, middleware, feature flags, and error paths can still emit data the schema does not describe.
2
3	- Validate path, query, header, and body inputs at the transport boundary with the same semantics as the published schema.
4	- Exercise and validate success and documented error responses in tests, including nullability, optional fields, formats, content types, and status codes.
5	- Reject or strip unexpected input properties according to the API contract and security model instead of passing them into domain or persistence code.
6	- Keep runtime validation failures attributable to operation and schema version without logging secret or personal payload fields.
7
8	See /openapi for the adjacent decision or procedure that completes this constraint.

Memories

Compatibility is evaluated from the consumer's view/openapiClassify changes to operations, parameters, security, schemas, enums, errors, and behavior before merging or publishing.

1	A server may accept a code change while generated clients, cached callers, gateways, or partner integrations fail. Compatibility depends on how existing consumers send and interpret data.
2
3	- Treat removed operations or fields, new required inputs, narrowed values, changed types, stronger security, and changed status semantics as breaking until proven otherwise.
4	- Review enum additions against clients that deserialize into closed sets even when the wire change is technically additive.
5	- Use a contract-diff gate against the last released schema and require an explicit version or migration decision for breaking changes.
6	- Provide an overlap period and deprecation evidence when consumers cannot update atomically with the server.
7
8	See /src/api for the rule or workflow that puts this decision into practice.

Examples are executable contract fixtures/openapiKeep request and response examples valid against schemas and representative of real success, failure, pagination, and authentication behavior.

1	Examples drive documentation, mock servers, tests, and human integration decisions. A pretty but invalid example teaches consumers a payload the server rejects.
2
3	- Validate every embedded and external example during the contract build.
4	- Use stable fictional data that demonstrates required and optional fields without copying production personal or secret values.
5	- Include representative errors and edge states, not only the smallest success response.
6	- Reuse examples in runtime contract tests or generated-client smoke tests so documentation changes receive executable feedback.
7
8	See /generated for the rule or workflow that puts this decision into practice.

Skills

release-openapi-contract/rootDiff, validate, generate, test, publish, and verify one OpenAPI contract and its downstream artifacts.

1	---
2	name: release-openapi-contract
3	description: Release an API contract change with generated clients or public documentation.
4	---
5
6	# Release Openapi Contract
7
8	Run this procedure when the affected surface changes, before the result is promoted to production. Record evidence for every step instead of accepting a plausible-looking result.
9
10	1. Generate the schema from the authoritative source in a clean environment and validate syntax, references, operation IDs, security, schemas, and examples.
11	2. Diff against the last released contract, classify every consumer-visible change, and stop for an unresolved breaking change or missing migration plan.
12	3. Regenerate supported clients, compile and smoke-test them against the candidate server, and verify old clients still satisfy the promised compatibility window.
13	4. Publish server, schema, documentation, gateway configuration, and SDK artifacts under one traceable release identity and intended order.
14	5. Fetch the deployed schema and call representative success and error operations, confirming runtime behavior and documentation match the released artifact.
15
16	## Exit criteria
17
18	The change is complete only when the expected behavior, failure behavior, and rollback path have all been exercised with representative data. Preserve the evidence with the change so the next operator can repeat the same checks.

Why this pattern

AI agents often edit handlers without updating the contract, mark breaking changes as harmless documentation, or generate clients from a schema different from the deployed server.

Built for API platform teams publishing OpenAPI contracts, generated SDKs, gateways, or partner documentation.

Keeps your assistant from:

Deploying a response shape not described by the published contract
Removing or narrowing a field without a compatibility decision
Generating clients from an uncommitted developer schema
Allowing examples to drift into invalid or misleading payloads

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25