A Deep Dive into OpenAPI

https://www.deployhq.com/blog/unlocking-seamless-development-and-collaboration-a-deep-dive-into-openapi

16•whatatimeline•7mo ago

Comments

waldekm•7mo ago

Another 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.

deployhq•7mo ago

Thanks for sharing it!

andregit•7mo ago

so...yaml for the win? :))

deployhq•7mo ago

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.

cyberax•7mo ago

Ugh. 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.

ludovicianul•7mo 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•7mo ago

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

cyberax•7mo ago

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.

deployhq•7mo ago

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

cyberax•7mo 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.

saturn_vk•7mo ago

I remember twirp being quite nice, too. Especially since it would also handle json from the same proto file.

dankobgd•7mo ago

So ai blog is now a "deep dive"

what-the-grump•7mo ago

Without a single line of code or example. Help I’m drowning.

deployhq•7mo ago

We ended up using this gem to implement OpenAPI: https://github.com/a-chacon/oas_rails, it was quite straightforward

ileanaishere2•7mo ago

from the first parragraph read like AI slop

speed_spread•7mo ago

Not 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.

SectorC: A C Compiler in 512 bytes

The F Word

Brookhaven Lab's RHIC concludes 25-year run with final collisions

Speed up responses with fast mode

Software factories and the agentic moment

Stories from 25 Years of Software Development

Hoot: Scheme on WebAssembly

OpenCiv3: Open-source, cross-platform reimagining of Civilization III

I write games in C (yes, C)

First Proof

Show HN: A luma dependent chroma compression algorithm (image compression)

The Waymo World Model

Al Lowe on model trains, funny deaths and working with Disney

Vocal Guide – belt sing without killing yourself

Start all of your commands with a comma (2009)

Reinforcement Learning from Human Feedback

Show HN: I saw this cool navigation reveal, so I made a simple HTML+CSS version

Selection Rather Than Prediction

Coding agents have replaced every framework I used

The AI boom is causing shortages everywhere else

A Fresh Look at IBM 3270 Information Display System

France's homegrown open source online office suite

72M Points of Interest

We mourn our craft

Unseen Footage of Atari Battlezone Arcade Cabinet Production

Where did all the starships go?

Show HN: Kappal – CLI to Run Docker Compose YML on Kubernetes for Local Dev

Learning from context is harder than we thought

Show HN: Look Ma, No Linux: Shell, App Installer, Vi, Cc on ESP32-S3 / BreezyBox

History and Timeline of the Proco Rat Pedal (2021)

A Deep Dive into OpenAPI

Comments

SectorC: A C Compiler in 512 bytes

The F Word

Brookhaven Lab's RHIC concludes 25-year run with final collisions

Speed up responses with fast mode

Software factories and the agentic moment

Stories from 25 Years of Software Development

Hoot: Scheme on WebAssembly

OpenCiv3: Open-source, cross-platform reimagining of Civilization III

I write games in C (yes, C)

First Proof

Show HN: A luma dependent chroma compression algorithm (image compression)

The Waymo World Model

Al Lowe on model trains, funny deaths and working with Disney

Vocal Guide – belt sing without killing yourself

Start all of your commands with a comma (2009)

Reinforcement Learning from Human Feedback

Show HN: I saw this cool navigation reveal, so I made a simple HTML+CSS version

Selection Rather Than Prediction

Coding agents have replaced every framework I used

The AI boom is causing shortages everywhere else

A Fresh Look at IBM 3270 Information Display System

France's homegrown open source online office suite

72M Points of Interest

We mourn our craft

Unseen Footage of Atari Battlezone Arcade Cabinet Production

Where did all the starships go?

Show HN: Kappal – CLI to Run Docker Compose YML on Kubernetes for Local Dev

Learning from context is harder than we thought

Show HN: Look Ma, No Linux: Shell, App Installer, Vi, Cc on ESP32-S3 / BreezyBox

History and Timeline of the Proco Rat Pedal (2021)