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