[nick238]

When OpenAPI opened the polymorphism door with 'oneOf' and the like, it seems like it turned into a shitty language written in YAML rather than being a good concise way to communicate API design.

Former company enforced OpenAPI specs to be able to publish any API endpoint, devs just wanted to push code, so they made vague shit specs because it's pulling teeth to do it the right way (didn't help that the spec enforcer couldn't fully read YAML documents with references, so copypasta was rampant)...

I guess there's the endless cycle of 1) a format is created, 2) the format evolves to do more, 3) winds up being overbearing, 4) a new format is created...

[mechanicalpulse]

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.

[pan69]

> 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...