# Pathrule Pattern: OpenAPI and Swagger Contract Workflow (1.0.0)
# ::pathrule:package:openapi-swagger-workflow

### [RULE] Choose one authoritative contract generation direction  (path: /openapi)
<!-- scope: folder | priority: high | strict -->

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.

- Declare contract-first or code-first ownership and identify the files reviewers change for paths, schemas, security, errors, and examples.
- Generate the distributable schema in CI from a clean checkout and fail when committed or published output differs.
- Do not patch generated clients or schema output manually; change the source and regenerate.
- Version and publish the exact schema used for server validation, documentation, gateway configuration, and client generation.

See /generated for the adjacent decision or procedure that completes this constraint.

---

### [RULE] Validate runtime traffic against the public schema  (path: /src/api)
<!-- scope: folder | priority: high | strict -->

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.

- Validate path, query, header, and body inputs at the transport boundary with the same semantics as the published schema.
- Exercise and validate success and documented error responses in tests, including nullability, optional fields, formats, content types, and status codes.
- Reject or strip unexpected input properties according to the API contract and security model instead of passing them into domain or persistence code.
- Keep runtime validation failures attributable to operation and schema version without logging secret or personal payload fields.

See /openapi for the adjacent decision or procedure that completes this constraint.

---

### [MEMORY] Compatibility is evaluated from the consumer's view  (path: /openapi)

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.

- Treat removed operations or fields, new required inputs, narrowed values, changed types, stronger security, and changed status semantics as breaking until proven otherwise.
- Review enum additions against clients that deserialize into closed sets even when the wire change is technically additive.
- Use a contract-diff gate against the last released schema and require an explicit version or migration decision for breaking changes.
- Provide an overlap period and deprecation evidence when consumers cannot update atomically with the server.

See /src/api for the rule or workflow that puts this decision into practice.

---

### [MEMORY] Examples are executable contract fixtures  (path: /openapi)

Examples drive documentation, mock servers, tests, and human integration decisions. A pretty but invalid example teaches consumers a payload the server rejects.

- Validate every embedded and external example during the contract build.
- Use stable fictional data that demonstrates required and optional fields without copying production personal or secret values.
- Include representative errors and edge states, not only the smallest success response.
- Reuse examples in runtime contract tests or generated-client smoke tests so documentation changes receive executable feedback.

See /generated for the rule or workflow that puts this decision into practice.

---

### [SKILL] release-openapi-contract  (path: /)

---
name: release-openapi-contract
description: Release an API contract change with generated clients or public documentation.
---

# Release Openapi Contract

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.

1. Generate the schema from the authoritative source in a clean environment and validate syntax, references, operation IDs, security, schemas, and examples.
2. Diff against the last released contract, classify every consumer-visible change, and stop for an unresolved breaking change or missing migration plan.
3. Regenerate supported clients, compile and smoke-test them against the candidate server, and verify old clients still satisfy the promised compatibility window.
4. Publish server, schema, documentation, gateway configuration, and SDK artifacts under one traceable release identity and intended order.
5. Fetch the deployed schema and call representative success and error operations, confirming runtime behavior and documentation match the released artifact.

## Exit criteria

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.