How do you actually fix API security issues at the spec stage before code exists?

Hello,

I've been thinking a lot about where API security problems actually get introduced, and it seems like most of them are baked into the spec before anyone writes a line of code. Missing auth on an endpoint, a sequential ID in a path, a sensitive field in a response schema these are all decisions made in the OpenAPI file.

But fixing them at the spec stage is harder than it sounds. The spec tells you what the API should do, not how it's actually implemented. A missing security block might be a real gap, or it might be handled by a gateway that isn't documented. A sequential ID might be fine if authorization is enforced elsewhere. So you end up with a list of findings and no clear way to know which ones are real problems versus which ones are just incomplete documentation.

For people who review specs regularly, how do you handle this? Do you treat every finding as real until proven otherwise? Do you have a way to distinguish between "the spec is wrong" and "the spec is incomplete"? And when you do find a real issue, what does the fix actually look like do you patch the spec, add a note, or escalate it to whoever owns the service?

I've been working on something in this space and I'm genuinely curious how others approach it, because the triage problem feels like the hardest part and nobody talks about it much.