A Deep Dive into OpenAPI
deployhq.com
A Deep Dive into OpenAPI
1–10 of 18 posts
Re: A Deep Dive into OpenAPI
#2Another 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.
Re: A Deep Dive into OpenAPI
#3so...yaml for the win? :))
Re: A Deep Dive into OpenAPI
#4Ugh. 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.
Re: A Deep Dive into OpenAPI
#5[deleted]
Re: A Deep Dive into OpenAPI
#6So ai blog is now a "deep dive"
Re: A Deep Dive into OpenAPI
#7Ugh. 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 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.
Re: A Deep Dive into OpenAPI
#8Ugh. 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 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
Re: A Deep Dive into OpenAPI
#9Not sure about the corporate advertising tone of the article, but I love OpenAPI. Having to work with various third party HTTP/JSON APIs all the time, I know I would rather deal with imperfect rigid generated client code than half-assed specs and shoddy examples. As a bonus, you can also generate your own server emulation for local testing, which is worth gold when dealing with real hardware.
Re: A Deep Dive into OpenAPI
#10Ugh. 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 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.
> 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.