apitypes: openapi spec

[hdonnay]

This series (split from #2266) adds JSON Schema documents for all the types exposed in the HTTP API and adds a way to generate the OpenAPI specification from those, a jq script, and some other loose files.

TODO

• Write+check all the "description" members for the JSON Schema documents.
• Write+check all the "description" members for the OpenAPI document.
• Check the generated API reference (./Documentation/reference/api.md) is at least as-useful as it was.
• Update documentation for contributors.

Coming later in series:

• Cross-check and adjust the API implementation.
• Implement the JSON marshaling and unmarshaling and check against the relevant JSON Schema.

[hdonnay]

@crozzy @BradLugo RFC: I currently have the go generate work driven by a shell script written in zsh. Is that super annoying? I suppose I could port it to a go script.

[hdonnay]

Crozzy and I went through the endpoints this afternoon and made sure they were all in the OpenAPI document. I'll take another pass on the description fields now that everything is at least in-place.

[hdonnay]

Okay, I think this is ready to go.

This adds a bunch of documentation and tooling, but only makes a few code changes. Those will come in a later PR.

[crozzy]

We've been through this and it LGTM, one ask I have is some doc to tell the developer how to update the openapi spec and perhaps how the different generation scripts interact.

[hdonnay]

Will do.

[crozzy]

Thanks for the guide, it worked with me after I updated the npm version

[hdonnay]

/fast-forward