Analyzing the OpenAPI Tooling Ecosystem

You can also record a blank video on your phone for 20 minutes and call that a movie. Would anyone watch it?

You can also build a house in days. Would it crack? Is it maintainable? What happens later? Who knows.

Barebones? Sure. But far from "a mess".

I've been advocating for finding a better data definition system for Moonwalk (and yes, that's my name on the post-2016 JSON Schema drafts- it's a great runtime constraint system, and it could still be useful for that purpose alongside a system more tailored to data definition).

[1] https://modern-json-schema.com/json-schema-is-a-constraint-s...

I genuinely think that the quality is beyond what exists in the GraphQl ecosystem.

Realised that writing a consistent API was more effort than it was worth compared to the one-shot setup cost of creating a set of basic components and re-using them to generate interfaces. Most of the API layer is just boilerplate and we can focus more on biz logic instead.

It may have more use to you if your API is quite large or re-uses a lot of components (e.g if you follow something like the JSON:API spec), because you can generate boilerplate from it then.

Can also be useful if there’s another team consuming the API, so you can design new endpoints and figure out the requirements before getting to work. That spec can then be used to generate mock servers or used for e2e testing.

That kind of seems backwards. If there was a official tooling, it would be Smartbear's (who else would provide it?) This clause actually seems to be designed to limit Smartbear's ability to use OpenAPI to push their products (and at the same time push OpenAPI as a credibly vendor-independent spec).

> Compare to gRPC/protobuf, where the specification and tooling have been developed together.

Yes, because it's a protocol pushed by one company, not pretending to be independent.

OpenAPI also has the problem of not providing any guidance on what the tooling ecosystem ought to look like, regardless of who implements the tools. You want enough leeway to encourage innovation, but if you don't put out _anything_, you get... well... this. Lots of tools that don't all fully implement things, and not much in the way of interoperable points of hand-off between tools beyond the format. And when many tools leave off some feature or another (most egregiously, external referencing - down the line in this blog post I'll actually show a concrete solution for that), just sharing the format isn't enough.

I'm hoping that this approach I'm sharing through these blog posts will help us start to shape the ecosystem more. For Moonwalk if nothing else (although I'd love to get 3.x into more of an interoperable state- let's make life better for people working with things now, not just years down the line).

Another advantage of OpenAPI is that you can write your specifications using Rust types (as we do at Oxide with Dropshot: https://docs.rs/dropshot)

edit: Apparently protobuf 3 does have oneof: https://protobuf.dev/programming-guides/proto3/#oneof. They look like they solve the problem but I can't vouch for it, and they appear to have some edge cases ("only the last member seen is used in the parsed message"). Thrift doesn't appear to, still.

And I do think being able to write the spec using Rust types is really nice -- you still get an OpenAPI document as an artifact, and (for external users) you get wide client compatibility.

gRPC requires brittle compilation of the protobuf definitions that has impacted every marshalling/serialization protocol for remote procedure calls since XDR.

Whether you like it or not, HTTP/JSON are the lingua franca of the internet (at least the API side of things). Protobuf is good if you are in control of both sides of the API, less so if you are just the server. It also is much less self-documenting than JSON Schema/OpenAPI.