The pragmatic answer: generate it if that is what your team will actually maintain, hand-author it if you can, and in both cases treat the output as an artifact that gets reviewed, linted and committed rather than as a build side effect.
The specific risk with generation is subtle. A generated document describes what the code does. A designed document describes what you promised. Those diverge in the places that matter most — a field you meant to be optional but the framework marks required, an internal endpoint that got annotated and published by accident, an error response nobody documented because the framework does not know about it. Generation makes the spec always current and never intentional.
The specific risk with hand-authoring is equally simple: it goes stale the moment someone ships a change without updating it.
Both risks have the same mitigation, which is why the argument matters less than people think. Lint the document in CI, run contract tests that compare the live API to the document, and fail the build when they disagree. Once the pipeline enforces agreement, how the file got written stops being interesting.
