Add Swagger Documention To The API

[arottersman]

Overview

• Adds django-rest-swagger to the project
• Documents inputs, outputs and descriptions of each of the AOI endpoints (the /analyzes and /rwd)
• Let's not worry too much about the exact content. The intent is to
  • make it easy for us to demo, and for the client to check on
  • provide an initial place to stick the docs

Connects #2185

Demo

Notes

• The example outputs make the docstrings real lengthy. I'll open an issue to look into moving them out of the implementation files, but for now we can make like @rajadain and set our editors to auto-collapse them.

• The example responses are shown as regular json, but the response currently returns stringified json. We'll fix the response type in Geoprocessing API: Responses should be proper json #2200

Testing Instructions

• vagrant ssh app -c 'cd /vagrant/src/mmw/requirements && sudo pip install -r development.txt'
• ./scripts/manage.sh collectstatic
• go to localhost:8000/api/docs/
• Test out each endpoint.

Here's an example analyze aoi:

{
  "type": "MultiPolygon",
  "coordinates": [[
    [
     [
      -74.97739791870116,
      40.08164651013995
    ],
    [
      -74.9734228849411,
      40.08164651013995
    ],
    [
      -74.9734228849411,
      40.08403526674243
    ],
    [
      -74.97739791870116,
      40.08403526674243
    ],
    [
      -74.97739791870116,
      40.08164651013995
    ]
    ]
 ]]
}

[rajadain]

Taking a look now.

[rajadain]

In addition to sudo pip install -r requirements.txt, I also had to run ./scripts/manage.sh collectstatic to get the docs to show up correctly.

[rajadain]

Hmm, the markdown isn't rendering correctly for me:

[arottersman]

Thanks, I've updated the testing instructions to include the collectstatic.

Not sure what's up with the markdown. Maybe check if the markdown package installed?

[rajadain]

I do seem to have it:

vagrant@app:/vagrant/src/mmw/requirements$ sudo pip list | grep -i markdown
Markdown (2.6.9)

[rajadain]

A hard refresh fixed it. It may have been a leftover from when I loaded the page with bad JavaScript before running collectstatic.

[rajadain]

This works well. Not sure where the api-docs URL is coming from:

[rajadain]

+1 tested. This works well, and reads well enough. A number of editors allow collapsing docstrings, like IntelliJ IDEA:

so I think long docstrings are fine. We should try to keep indentation consistent throughout the file though, to ease tab navigation.

[rajadain]

Can we clean up the spacing here to be more even?

Since we use 4-space indentation in our code, we should try and use the same here.

[arottersman]

I'll normalize these before merging.

[arottersman]

Thanks for reviewing! I am also not sure where the api-docs url comes from...

[arottersman]

I've prettified the JSON in the docstrings. Will merge when the build completes.