OpenAPI: make the contract load-bearing

Take a small HTTP API (your own or a 3-endpoint orders service) and make its OpenAPI 3.1 spec the enforced source of truth: codegen a typed client, validate requests at the edge, and gate breaking changes in CI — then prove a breaking change is blocked before merge.

• Write or extract an OpenAPI 3.1 spec for at least three endpoints (e.g. POST /orders, GET /orders/{id}, GET /orders) with tight schemas: explicit types, explicit required arrays, reused $ref components, and at least one security scheme. State whether you went spec-first or code-first and why.
• Generate a typed client (or server stubs) from the spec — openapi-generator, openapi-typescript, oapi-codegen, or your stack's equivalent — and use it from a small consumer so requests are no longer hand-rolled.
• Add request validation at the edge: a middleware that validates incoming requests against the spec before the handler runs, returning a precise 400 that names the offending field on a malformed body.
• Wire a breaking-change gate in CI: run oasdiff (or equivalent) to diff the PR's spec against the base branch and fail the build on any breaking change. Capture the passing run on a safe change.
• Open a PR that makes a breaking change — add a required request field, remove a response field, or narrow a type — and show the CI gate failing with the exact change category reported.
• Fix the breaking PR by making the change compatible instead (add the field as optional, keep the response field) and show the same gate now passing.
• Demonstrate the docs are generated from the same spec, so the rendered docs cannot contradict the contract.

• A before/after CI log: the breaking PR fails with oasdiff naming the specific breaking rule (e.g. api-required-request-property-added), and the compatible PR passes.
• The generated client compiles with precise types — no any/unknown for fields the spec defines — proving the schemas are tight enough for honest codegen.
• A malformed request to the validated endpoint returns a 400 naming the offending field, captured as a real response, not described.
• A one-paragraph write-up: spec-first vs code-first choice and why, and which enforcement layers (codegen, edge validation, diff gate) defend against which failure mode.