Except in practice the only accurate and complete openapi specs I see are generated from code annotations or are used to generate the service code. It’s a particular form of worse is better where overall you end up doing the same work as in the soap/wsdl days if you want to finish the job, but because in the beginning you can just hammer out undocumented code it feels much easier. Regrettably many developers stop at 80% and produce openapi specs that have the appearance of completeness without actually being complete.
My preferred approach is to use the OpenAPI as a spec, i.e. to drive the implementation, rather than just documenting the implementation. I wrote a little Python framework [1] to help me put that approach into practice.
