[sunshowers]

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.

[throwawaymaths]

If you're building maintainable servers you should write the doc first and the codegen from there. Otherwise you're gonna be in a world of hurt when some junior changes your datatype or if you need to version and maintained both versions simultaneously from the same or similar endpoints.

[sunshowers]

You're right that this is a very difficult problem, but writing the document first doesn't give you much over generating it from types.

We actually have a plan for supporting multiple versions, and conversions between the corresponding types, using Dropshot as the place where that's coordinated.

[throwawaymaths]

> writing the document first doesn't give you much over generating it from types.

There's a required top-level parameter called version. As you are writing the document, it's in your face.

[sunshowers]

With Dropshot, the version is passed in as a function argument to the OpenAPI generator.

[throwawaymaths]

You will find out the problems with your approach.