I'm honestly disappointed how OpenAPI keeps being used over and over as documentation, and extremely rarely as what it excels at, which is specification.
We build all kinds of frameworks with routing and request/response validation, and then extract that into OpenAPI format, ofteng having to jump through hoops to adapt our internal data types and structures into those supported by JSON Schema. Instead, we could be doing the opposite: writing the OpenAPI spec first, and use tooling to make routing and validation based on it in an automated way. That has been done before [0] [1], but we're still just scratching the surface of what is possible.
Yes, I am aware that it's not easy to manually write the specs using JSON or even YAML, but we need a better focus on tooling around it; currently only Stoplight [2] gives a solid level of support in that area.
[0] https://connexion.readthedocs.io