Design and build annotated API using django and swagger with documentation

[meganmckissack]

(http://swagger.io/)

[hassanshamim]

Seems like an easy addition: https://github.com/marcgibbons/django-rest-swagger

[ron-s]

added swagger (branch: add-swagger) using official framework tutorial:
http://marcgibbons.github.io/django-rest-swagger

[jimtyhurst]

The Budget web service is now displaying a Swagger-generated API description, but it is not as useful as it could be. If you look at a sample, like Swagger's Pet Store example, the endpoint descriptions specify parameters, HTTP error code conditions, sample JSON message content, etc., but our API description has none of those. If someone can tell me the annotations or documentation format for specifying those values for a Python function, I would be glad to enhance the documentation. I know how to use Swagger annotations for Java methods, so I did some web searching, but I could not find how to do it for Python.

[MikeTheCanuck]

Updated title to reflect the gap that @jimtyhurst identified.

[jimtyhurst]

See marcgibbons/django-rest-swagger#549 which explains that it is a known issue that the framework that we have chosen does not implement the parts of the Swagger specification that deal with path parameters, query parameters, possible values of parameters, sample return values, error conditions, etc. Also see hackoregon/emergency-response-backend#21 which suggests a workaround.

[mxmoss]

Seems like this issue has been addressed. Can we close it?