Specify the API using swagger

[arschles]

This issue is for investigating swagger server stub code generators for Python & Django Rest Framework, and then if there is a suitable one that won't require a large refactor of this codebase, doing the following:

1. Writing a swagger specification for the controller's full API
2. Generating server stubs and refactoring this codebase into the stubs
3. Generate the Go client bindings in deis/builder and deis/workflow-cli (each to be done in a separate issue in the respective repository)
   1. The changes in deis/workflow-cli may move to a new repo if Pull the code client code into a Go SDK workflow-cli#18 is completed first

[helgi]

You are duplicating yourself, up to you which one you keep open

#289

[arschles]

Ugh sorry. Closing the other one since this one is more specific

[jgmize]

https://github.com/marcgibbons/django-rest-swagger may be helpful for this

[helgi]

Already tried it - doesn't work and isn't maintained :(

Our best bet is Marshmallow (a schema / serializer like project) and the DRF integration for that. Marshmallow has swagger and json API support as well.

Looks like DRF 3.0 is going to have Core API support (sponsored by Mozilla) but it may not be ready anytime soon

[helgi]

Just leaving this here for now https://github.com/civisanalytics/swagger-diff, https://github.com/keis/swagger-markup and http://swagger.io/using-swagger-to-detect-breaking-api-changes/