Draft a formal api spec (Swagger spec)

[0xdade]

Is your feature request related to a problem?
The API is a mess right now. Who knows what goes in! Who knows what comes out! I wrote it and I don't even know all the code paths.

Describe the feature you'd like
Use a swagger spec to define the behavior of the API and then adhere to that swagger spec.

Have you considered alternative ways to get this feature
I originally started writing a wiki page on the topic, but that was kind of silly as a swagger spec is literally meant for this.

Additional context
This is part of building a stronger focus on engineering excellence. The act of creating the spec itself doesn't introduce immediate functional value, but it provides a lot of value to building and maintaining the API.