padosoft-openapi-spec-workflowlisted

# OpenAPI spec workflow In a spec-first repository the contract is published and **other projects depend on it**. A field added in one place and forgotten in four others does not fail here: it fails in the consumer, after the release. This skill is the sync list and the verification loop. --- ## 1. Before touching anything: what kind of change is it? | Change | Bump | Consumers | |---|---|---| | New optional field, new endpoint | **minor** | Keep working | | Bug fix, mock or doc update | **patch** | Keep working | | Field removed, type changed, field made required | **major** | **Break** — announce it | Making an optional field required is a breaking change even though nothing is deleted. If you are about to do it, say so before writing code: it is usually cheaper to add a second field. ## 1b. Where the contract comes from, and what it must not invent A specification maintained by hand, next to the routes rather than from them, drifts the moment a route, a permission or a path parameter changes — and nothing fails. - **Generate the first contract from the same concrete route table the server uses.** That catches an omitted route and a method/path mismatch immediately, which is exactly what review does not catch. - **Keep the transport generator separate from the domain schemas.** Generic placeholders are useful for discovery, and they must never be mistaken for a complete versioned payload contract or for proof that a client can be generated from it. - **Refere