Fail CI when the API spec drifts

An OpenAPI file helps a new person only if it matches the routes. The way to keep that true is to fail the build when it does not.

Document the failures too

A route that ships has a path, a request schema, and the status codes it actually returns. A 400 carries the field list. Then 401, 403, 404, and 409 when two writes hit the same row. Do not document 200 and leave the failures as a surprise in the client.

Generate the spec from the route definitions where you can, and check it into the repo where you cannot. A spec that lives in a wiki describes an earlier version of the service. People will still try to use it.

Diff it in the pipeline

RecordUpdate:
  type: object
  required: [status]
  properties:
    status:
      type: string
      enum: [open, closed]

The job installs, runs the tests, and boots the API far enough to serve the spec. A later step diffs that spec against the one the client is built with. A new required field without a spec change is a red build.

What a new person clones

They clone the repo, copy an env file of fake values, and run the same job. The README is that command. A second getting-started guide will drift, and the drift is what costs the first day.

The spec will not explain why a route checks the row and not only the role. That rule sits next to the codes, in the handler checklist.