So ai blog is now a "deep dive"
Without a single line of code or example. Help I’m drowning.
A Deep Dive into OpenAPI
11–18 of 18 posts
Re: A Deep Dive into OpenAPI
#12Earlier quoted context omitted.
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.
Agreed. 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
You 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/...
Do an experiment, take a Protobuf spec for some Google API and convert it into OpenAPI.
Re: A Deep Dive into OpenAPI
#13so...yaml for the win? :))
So, we ended up by using https://rubygems.org/gems/oas_rails which does the heavy work and generates almost everything. We only had to document the endpoints.
Re: A Deep Dive into OpenAPI
#14So ai blog is now a "deep dive"
Without a single line of code or example. Help I’m drowning.
We ended up using this gem to implement OpenAPI: https://github.com/a-chacon/oas_rails, it was quite straightforward
Re: A Deep Dive into OpenAPI
#15Earlier quoted context omitted.
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.
Agreed. 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
We have used the gem: https://github.com/a-chacon/oas_rails, and we didn't need to write the specs, just comment the endpoints
Re: A Deep Dive into OpenAPI
#16Another way to create an API spec is by using Dev Proxy: https://learn.microsoft.com/microsoft-cloud/dev/dev-proxy/ho... . It’s an easy way to get started from an existing API.
Thanks for sharing it!
Re: A Deep Dive into OpenAPI
#17So ai blog is now a "deep dive"
from the first parragraph read like AI slop
Re: A Deep Dive into OpenAPI
#18Ugh. OpenAPI: just say "no". It's WAY too verbose, and there are usually many ways to shoot yourself in the foot. Protobuf-based APIs are much nicer to work with. Either via gRPC, or via ConnectRPC.
I remember twirp being quite nice, too. Especially since it would also handle json from the same proto file.