Spec the API using Swagger

[pfrazee]

Swagger is a spec and toolset for specifying Web APIs using YAML. It's also part of the OpenAPI standard. The advantages of using it are:

• Concise specification language, in yaml (yay)
• Automatic code generation for both client and server, if you want it
• Automatic documentation generation (very handy)
• Automatic test generation

You can see example specs, and the auto-generated documentation (on right), in their editor app: http://editor.swagger.io/#/

We could host the auto-generated docs as the HTML response to the /v1/ endpoint.