Why not push for them to become something more? Documentation for humans is good, but you know what's better? Documentation for computers so that we don't have to build integrations anymore!

I would love to see how this could be realistically done. I recall this being attempted with WSDLs, but there was still a ton of man hours required to integrate with an endpoint.

There is still always an impedance mismatch between the server representation and what the client representation that needs to be fixed.

Like ORMs, such integration automation will always be, at best, a leaky abstraction that makes the easy bits easier, and the hard bits harder.

I'm not sure the point about the ORMs is entirely true. I see what you're saying, but the API boundary should be the canonical definition (unlike an ORM where the database might be), and the server and client need to conform to that, so there shouldn't be leakage.