API Blueprint

I've experienced the mind-numbing frustration of API specs that don't match the implementation, which is why I have embraced the concept of requiring the spec to be part of the implementation. For example, the express-openapi package for Node.js expects the specification to be supplied as a property of the very function implementing the operation. This permits middleware to access the OpenAPI specification directly and utilize it for coercion and validation of requests and responses, so you get several birds with one stone.

I've also experienced enterprise OpenAPI deployments where the API specifications were owned by a separate enterprise API architecture team and were fed into some central consumer-facing documentation portal along with whatever unbeknownst infrastructure sat between the application and the Internet. Developers had access to the spec repository, but API architects reviewed PRs and made any recommendations for normalizing interfaces or using existing or canonical types.

Either way works, IMNSHO.

Edit: I should also say that I have likely misrepresented the deficiencies I experienced with API Blueprint. Take it with a grain of salt; I literally do not remember because it's been ... checks code ... nearly five years since I touched that project. The issue I ran into may have been as simple a problem as providing two example POST requests with slightly different payloads or two example HTTP 200 responses with slightly different response bodies. This is something that API documentation might often include to show multiple common use cases. It may have not have even been part of the actual spec or it may have been only a limitation of the specific UI renderer I was using.

> When OpenAPI opened the polymorphism door with 'oneOf' and the like

Technically this is a feature of JSON Schema, not OpenAPI. But since OpenAPI is a superset of JSON Schema...