I agree. API-first is the way! Change your schema, auto-generate types into your code and use them for your server definition. It's just faster and more secure this way. Use api-fiddle.com or spotlight.io to work with the schemas (branching, sync with Github).

In a fully typesafe world, it should be pretty hard to derive from the shema this way.

Rswag is still my favorite openapi-related project. You write integration tests against the server and get an openapi spec as output. But thats for rails.

Just have to be a bit careful mentioning it in front of non tech folks who'll inevitably ask "what's arsewag?"

As others suggested, I would diff against a generated one, then potentially treat the generated one as source of truth in the future... Then diff accordingly as it changes.

You can simply diff it. Define the OpenAPI spec, have the framework generate a spec, compare.

You could generate a spec for the service and then diff to the expected perhaps.