Describe endpoints with OpenAPI 3

[carboxylman]

We have an existing prose doc that we should really convert to something formal. OpenAPI is the best way.

[hardiksurana]

Existing documentation: https://docs.google.com/document/d/1OVML1IMh4bHgXakijQxDG2KhwpwYipb1bUumZ-TQ5hs/edit?usp=sharing

[carboxylman]

Here is a reasonable place to start, perhaps: https://github.com/jmcarp/flask-apispec (https://flask-apispec.readthedocs.io/en/latest/usage.html).

Because our APIs often accept/output object hierarchies, we will have a bunch of manual tweaking. We also probably want to filter out some endpoints entirely, and possibly hide admin or other privilege bits.

[carboxylman]

Here's one I recently hand-wrote for a c++ app: https://gitlab.flux.utah.edu/powderrenewpublic/nexran/-/blob/master/etc/northbound-openapi.json (nice, gitlab now has integrated swagger rendering!)