search

hackoregon / team-budget

Repo for the Budget team's backend code
MIT License
6 stars 4 forks source link

Design and build annotated API using django and swagger with documentation #18

Open meganmckissack opened 7 years ago

meganmckissack commented 7 years ago

(http://swagger.io/)

hassanshamim commented 7 years ago

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

ron-s commented 7 years ago

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

jimtyhurst commented 7 years ago

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 commented 7 years ago

Updated title to reflect the gap that @jimtyhurst identified.

jimtyhurst commented 7 years ago

See https://github.com/marcgibbons/django-rest-swagger/issues/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 https://github.com/hackoregon/emergency-response-backend/issues/21 which suggests a workaround.

mxmoss commented 7 years ago

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