What a load of nonsense. OpenAPI is a documentation standard for HTTP APIs. So, this is an apples and oranges comparison that starts off on the wrong premise.

Some of those APIs might be REST APIs in the strict hypermedia/ HATEOAS sense as popularized twenty years ago by some proponents of this. However, looking back that mostly did not get very popular. I actually met with Jim Webber a couple of times. He co-authored "REST in Practice", which is sort of the HATEOAS bible together with the og. HTTP spec by mr. REST Roy Fielding. Lovely guy but I think he moved on from talking a lot about that topic. He's been at neo4j for more than a decade now. They don't do a lot of HATEOAS over there. I remember having pointless debates about the virtues of using the HTTP Patch method with people. Thankfully that's not a thing anymore. Even Jim Webber was on the fence about that one.

Most people these days are less strict on this stuff and might create generic HTTP REST APIs that may or may not do silly things as making every request an HTTP POST like SOAP, Graphql, and indeed Grpc tend to do. Which is very un HATEOAS like but perfectly reasonable if you are doing some kind of RPC.

Most APIs trying to do some of notion of REST can and probably should be documented. For example using OpenAPI.

Most modern web frameworks support OpenAPI directly or indirectly and are nominally intended to support creating such REST APIs. There's very little reason not to support that if you use those. Things like Spring Boot, FastAPI, etc. all make this pretty easy. Your mileage may vary with other frameworks.

Grpc is a binary RPC protocol that gets used a lot for IMHO mostly invalid reasons and assumptions. Some of those assumptions relate to assuming applications spend a lot of time waiting for network responses and parsing to happen and that making responses smaller and easier to parse makes a significant impact. That's only true for a very narrow set of use cases.

In reality, textual responses compress pretty well and things like JSON parsers are pretty fast. Those two together mean that the amount of bytes transferred over the network does not really change significantly when you use Grpc and the time waiting for parsing relative to waiting for the network IO is typically orders of magnitudes less. Which leaves plenty of CPU time for parsing and decompressing stuff. This was a non issue 20 years ago. And it still is. I routinely added compression headers to web servers twenty years ago because there were no downsides to doing that at the time (minimal CPU overhead, meaningful network bandwidth savings). Parsers were pretty decent 20 years ago. Etc.

Using RPC style APIs (not just grpc) has two big issues:

- RPC protocols tend to be biased to specific implementations and languages and rely on code generation tools. This can make them hard to use and limited at the same time.

- They tend to leak internal implementation details because the APIs they expose are effectively internal APIs.

The two combined makes for lousy APIs. If you want an API that is still relevant in a decade or so, you might want to sit down and think a little. A decade is not a lot of time. There are lots of REST APIs that have been around for that long. Most RPC APIs from that long ago are a bit stale at this point. Even some of the RPC frameworks themselves have gone a bit stale. Good luck interfacing with DCOM or Corba services these days. Or SOAP. I'm sure there's a poor soul out there wasting time on supporting that shit in e.g. Rust or some other newish language. But don't get your hopes up.