The projects I work on generate OpenAPI docs at runtime based on annotations in the server source code, so they're always guaranteed to be in sync with the actual API. We've had to add some custom logic to clean things up a bit (e.g., in places where we have custom JSON serialization logic) but luckily the library we're using has hooks for that purpose and it hasn't been a huge pain point.
But like others have said, the client code generators leave a lot to be desired. For example, I have yet to find one that properly deals with recursive data structures like an arbitrarily-nested tree structure with multiple node types. Several of them just flat-out crash, and the ones that don't generate code that won't compile or that bombs out. We've had to resort to hacks like tagging the recursive structures' descriptions with magic keywords that trigger a postprocessing step to fix up the generated code.
But I don't really view this as a problem with OpenAPI per se. The data structures in question can be correctly and unambiguously described in the OpenAPI JSON document.
But like others have said, the client code generators leave a lot to be desired. For example, I have yet to find one that properly deals with recursive data structures like an arbitrarily-nested tree structure with multiple node types. Several of them just flat-out crash, and the ones that don't generate code that won't compile or that bombs out. We've had to resort to hacks like tagging the recursive structures' descriptions with magic keywords that trigger a postprocessing step to fix up the generated code.
But I don't really view this as a problem with OpenAPI per se. The data structures in question can be correctly and unambiguously described in the OpenAPI JSON document.