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.
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:
swagger
directory under the deis/workflow-manager repositoryMakefile
in this repository must have a build target to generate server "stub" codeMakefile
indeis/workflow-manager
must have a build target to generate client codeAlso, 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.