define the API with swagger

[arschles]

instead of, or in addition to having the api-architecture.md document, we should have a swagger spec to define the API so that we can predictably change the API and publish documentation if we need to.

Implementation details:

• go-swagger is a useful tool for generating Go code from Swagger 2.0 specifications, but other tools can be used instead. The only requirement is that the tool must be easy to install and easy for developers to work with
  • For example, the go-swagger tool is written in Go, so it's a self contained binary with good documentation
• [x] The swagger specification should mirror the endpoints that are currently in doc/api-architecure.md
• [x] The swagger specification should live in a swagger directory under the deis/workflow-manager repository
• [x] The Makefile in this repository must have a build target to generate server "stub" code
• [x] The Makefile in deis/workflow-manager must have a build target to generate client code
• [x] The implementation in this server should be moved into the server stubs (#138)

Also, the items in the above bullet points should be split up into smaller, logical units of work and submitted as small, easy to review & test PRs.

[arschles]

Moving out of RC1, as this is not essential for the RC

[slack]

Is this done?

[arschles]

yes, done by #41, deis/workflow-manager#43, #135 and deis/workflow-manager#44. closing