Create Swagger docs for public API endpoints

[kellyi]

Overview

This PR creates a set of Swagger docs for the application's public API endpoints, accessible at /api/docs.

The inline docstrings are currently accurate for all endpoints, and the contributors, contributor types, countries, and facilities endpoints are both documented and working through the UI.

I had substantial trouble getting the facility lists documentation to work, so I delayed fleshing that out until #349. Django REST Swagger deprecated using inline YAML to declare a schema and fields for each endpoint in version 2, and lower versions are not compatible with our existing setup.

Conceivably we could just drop the api/facilities-list endpoints from the publicly documented API altogether for now and come up with a better solution later. The other interactive endpoints are working as expected.

Connects #88

Demo

Testing

• get this branch then ./scripts/update
• ./scripts/manage resetdb and ./scripts/manage processfixtures
• visit localhost:6543 and click on the API link in the navbar, verifying you are taken to the Swagger docs
• try out the interactive docs for facilities, countries, contributors, and contributor_types
• back on 6543, create an API token, then copy it to the clipboard
• return to the API docs and click the "Authorize" button, then enter Token <YOUR_TOKEN> as the auth and click authorize
• verify that the "/api/facility-lists` section is there

[jwalgran]

Do we know what this [ BASE URL: ] thing is?

[kellyi]

Interesting, we should be able to add that, however:

marcgibbons/django-rest-swagger#681

[kellyi]

I think we may be able to configure the base url somewhere here so I'll try it out tomorrow.

[kellyi]

This ended up not working. I asked a question here marcgibbons/django-rest-swagger#681 about whether there's an alternate way to fix this, so if someone answers we can circle back to this later.

[kellyi]

I tried out adding a url argument to get_swagger_view and also adding BASE_PATH and BASE_URL values to SWAGGER_SETTINGS. None of these worked. I'll post on the issue linked above to ask if anyone has discovered a workaround.

[jwalgran]

This is a great start. Thats for struggling with We will be evolving this over time, I imagine.

I made a few comments.

[jwalgran]

Consider adding a sentence or two to the commit message explaining why we need to pull in this additional library.

[kellyi]

Sounds good. I'll update the commit message. Essentially this is the DRF recommended library to use for creating a documentable schema: https://www.django-rest-framework.org/api-guide/schemas/#schemas

[jwalgran]

This is no longer correct since we have merged #341. We now return item_count instead of items. There is new items endpoint that is being picked up automatically, but the page and pageSize parameters aren't appearing.

[kellyi]

Cool -- I updated these in 0404a56

Note that the parameters are still not accurate for the facility lists endpoints.

[kellyi]

19e788f

shortens the "next" url to make it possible to remove # noqa

[jwalgran]

Thanks for making the fixes. Looks good.

Please make sure we have logged a follow up issue that enumerates the remaining items we have to fix.

[kellyi]

Thanks! #349 is for fixing the facilities list documentation.