this is a huge pain point OAS 3.1 is "basically perfect" and I wish so much we could transition to it, but we expose our API via Swagger.io, so we can't transition yet.

I think OpenAPI is losing out the sexiness battle against graphQL, but I will say this: There's a way in which OpenAPI inherently makes you reflect on distributed systems errors. What are you going to do if a request 500's and you need to maintain consistency between two data systems?