hasadna / hasadna/OpenTrainCommunity

rest_framework_swagger's API doc generation can't handle query params

Open
#40 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
HTML
Stars
25
Forks
13
PR merge metrics
No merged PRs in 30d

Description

https://github.com/hasadna/OpenTrainCommunity/blob/e6bfe77b33ad5b8b148e15b5b3f845dadb652158/train2/train2/urls.py#L23

rest_framework_swagger generates docs at:
http://otrain.org/api/docs

API endpoints that require query parameters (as opposed to URL-supplied parameters) do not have those parameters generated in the documentation. Pressing the `Try it out!` button, for instance, will return a 500 error for:

http://otrain.org/api/docs/#!/general/general_goto_sleep
http://otrain.org/api/docs/#!/routes/routes_all_by_date
http://otrain.org/api/docs/#!/stats/stats_from_to_full
http://otrain.org/api/docs/#!/stats/stats_path_info_full
http://otrain.org/api/docs/#!/stats/stats_route_info
http://otrain.org/api/docs/#!/stops/stops_from_to
http://otrain.org/api/docs/#!/trips/trips_list_compact

This is a known issue with this package ever since YAML was deprecated. The various workarounds mentioned on the internet don't seem to work with `list_route`'s defined on `ViewSet`s, which is how the functions are defined. Also, the rest_framework_swagger package is not being maintained.

Some related discussions:
https://github.com/marcgibbons/django-rest-swagger/issues/549
https://github.com/marcgibbons/django-rest-swagger/issues/629
https://stackoverflow.com/questions/41104615/how-can-i-specify-the-parameter-for-post-requests-while-using-apiview-with-djang
https://stackoverflow.com/questions/28203070/how-to-show-query-parameter-options-in-django-rest-framework-swagger

![image](https://user-images.githubusercontent.com/1482729/41990685-e092b7ac-7a4b-11e8-927c-4d922f91f193.png)

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.