Re:Analyzing the OpenAPI Tooling Ecosystem
by throwawaymaths on Sunday September 22, 2024 @02:30PM
(#41618946)
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.
Re:Analyzing the OpenAPI Tooling Ecosystem
by sunshowers on Sunday September 22, 2024 @04:16PM
(#41619699)
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.
Re:Analyzing the OpenAPI Tooling Ecosystem
by throwawaymaths on Sunday September 22, 2024 @10:40PM
(#41621964)
> 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.
Re:Analyzing the OpenAPI Tooling Ecosystem
by sunshowers on Monday September 23, 2024 @12:08PM
(#41627574)
With Dropshot, the version is passed in as a function argument to the OpenAPI generator.
Re:Analyzing the OpenAPI Tooling Ecosystem
by throwawaymaths on Monday September 23, 2024 @01:55PM
(#41628715)
You will find out the problems with your approach.
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.