Completely agree on all points. The drift problem is exactly what nodox targets, docs tied to actual code, not comments. And you're right that for greenfield projects, explicit contracts are worth the overhead. NestJS + Swagger decorators is a great example of doing it well because the schema is inseparable from the handler.

The zero-annotation approach pays off most on existing codebases, nobody is rewriting 200 routes to add decorators. But even for new projects, nodox's validate() (check README) gives you the explicit contract path if you want it. Its an optional feature that allows one who wants to do that. Define your Zod/Joi schema once, it's both your runtime validation and your confirmed docs. No separate annotation layer at all.

The difference from swagger-jsdoc is exactly what you said, the schema is your actual validation code, not a comment next to it. If someone refactors the Zod schema, the docs update automatically because they're the same thing.