3 ms·
I would say being verbose is a positive thing. It removes the need of having additional (and usually out-of-sync) documentation. Plus all the tooling around it
by ludovicianul 1y ago
I would say being verbose is a positive thing. It removes the need of having additional (and usually out-of-sync) documentation. Plus all the tooling around it that allows you to keep public Dev documentation in sync with min effort.
- resonious 1y agoAgreed. The extra stuff you get "for free" from the OpenAPI ecosystem is well worth the extra time it takes to write the spec. If you don't want things like client/server generators and documentation, then sure it's not great
- cyberax 1y agoYou still need to write a spec with protobufs. It's just that the spec is much more succinct and easy to read. And you can generate docs from it. E.g.: https://cloud.google.com/appengine/docs/admin-api/reference/rpc/google.cloud.location#listlocationsrequest https://cloud.google.com/appengine/docs/admin-api/reference/... Do an experiment, take a Protobuf spec for some Google API and convert it into OpenAPI.
- deployhq 1y agoWe have used the gem: https://github.com/a-chacon/oas_rails https://github.com/a-chacon/oas_rails, and we didn't need to write the specs, just comment the endpoints
- cyberax 1y ago> I would say being verbose is a positive thing. No, it's not. A description of a single method can often span a couple of screens, and still not cover everything. In addition, YAML is not easily composable, so you end up with files that are megabytes in size. This is completely useless for humans, unless you start using third-party tools to split the file into parts. Protobuf-based protocols are also much better specified, and they don't have multiple ways to pass in data. Meanwhile, OpenAPI supports: headers, path queries, multiparts, forms with various encodings, uploads, etc.