By far the worst part of OpenAPI is how aspirational the documentation seems to remain. It seems it is always leveraging things that almost worked in the previ

By far the worst part of OpenAPI is how aspirational the documentation seems to remain. It seems it is always leveraging things that almost worked in the previous version with advice on how it should be done. But if you do the new way, expect that about half of the tooling you find won't work. It really is WSDL all over again. Where if you buy in to a specific vendor's tooling, and don't leave it, things actually do mostly work as advertised. You want to piecemeal anything, and holy crap at the unexpected pitches.