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