> I find it striking that in the same day I saw a video about how someone "Made an API in 20 minutes with one prompt" and this

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.

Yeah this article is more about how we (the OpenAPI Initiative) are designing the next versions of the OpenAPI Specification than it is about how to use it. The diagram does include both an OAD generator and editor, intended to encompass both code-first and description-first (which doesn't make too much difference for this blog post). The Moonwalk article is definitely more general purpose! This is "OK Moonwalk has a great vision, but how do we actually make it a real spec?" I've been using variations of this diagram in the weekly Moonwalk calls for the past month or two.

Part of the problem is that OpenAPI depends on JSON Schema and JSON Schema is a runtime constraint system, not a data definition system [1]. That shows up in the diagram with the three colors crammed into the "Interface Modeling and Validation" area because the boundary between those three ends up being very weird. And there's no standard for using JSON Schema as a data definition system... people just started kinda doing stuff.

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

There's a lot of new companies that have started to address this issue. One of which I work at: https://www.speakeasy.com/

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

How is Swagger a mess? It produces perfectly readable documentation and testing mechanisms.

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

If you haven’t yet, I highly recommend to check FastAPI for your python backend: https://fastapi.tiangolo.com/. OpenAPI is a core part of it, making it simple to integrate with other tools such as docs and clients generator

I keep mixing them up now too.

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.

For a while, the "P" key on my laptop wouldn't work reliably... which is really annoying when your work is all focused around OpenAPI but everyone else keeps assuming AI :P

I actually looked at that one, too, and know the person (or one of the people) that started it. Their classification is better than tools.openapis.org (slightly embarrassing, but we don't have anyone who has volunteered to curate it beyond minimal PR approvals, so...). Although you still fundamentally see the same problems. And it was more convenient for me to point to the messier list for the purpose of this blog post, anyway!

The output will only really be as good as what you describe, really, and if you’re only using it for yourself it might feel like overkill, particularly if you want the spec as the source of truth and have to rewrite your API to fit a generated interface.

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.

You might like zod-openapi (https://github.com/samchungy/zod-openapi). You write Zod schemas which, on their own, are a great way to define a validation and de/serialization layer in your API and you then can additionally use them to generate an OpenAPI doc.

OpenAPI is only useful if you intend for your project to become bigger than what fits in your head or if you intend to keep a project alive for long enough to start forgetting things you did a while back.

I personally just rely on FastAPI + Pydantic.

My involvement started in the lead-up to OAS 3.1 so I don't have any insight into the Smartbear/OpenAPI Initiative hand-off. Yes, the decision to be vendor-neutral is part of the reason the ecosystem is so fractured. But most technical standards are vendor-neutral and work just fine.

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

> but with the requirement that there wouldn't be official tooling offered with it --- arguably to protect Smartbear's investment in Swagger

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.

Thanks! :-)

GRPC and Thrift can't express ADTs (enums with data) easily, but OpenAPI can. That's worth a lot in my book.

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.

This "stuff" allows for easy exchange of API definitions and Arazzo goes to the next level to define the semantics of the process of combining API calls.

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.

Apples and oranges? gRPC might sometimes fit the bill for server-to-server use cases, but it's completely unsuitable for integration with SPAs; grpc-web was never well-supported, and is now dead. I don't understand the "want to vomit" perspective. That implies that adding protoc to your build toolchain and using an opaque binary format/protocol is somehow much more palatable than well-documented JSON / REST over HTTP. What am I missing?

ConnectRPC here but yeah same idea.