New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Attempt to document API via Django REST Framework / Core API #1797

Merged
merged 6 commits into from Apr 19, 2018

Conversation

Projects
None yet
2 participants
@toolness
Contributor

toolness commented Apr 18, 2018

This attempts to implement the solution suggested by @jseppi in #1698 (comment), whereby we use DRF's built-in support for API documentation.

Specifically, it adds an endpoint at /api/docs/ that looks like this:

api-docs

Clicking the "INTERACT" button brings up a modal that allows users to tinker with a specific API endpoint:

interact

Notes

  • It seems like DRF has embraced something called Core API, which is "a format-independent Document Object Model for representing Web APIs". Sadly, it seems somewhat scant on documentation; for instance, some code examples in the DRF docs use a module called coreschema which has a githubo repo with no README.

    Based on a cursory look, it seems like the plumbing provided by this API could be useful for automatic parameter validation, but given the apparent lack of maturity, I'm hesitant to start using it for anything other than documentation right now.

  • I was having some problems running flake8. Apparently the version we use is supposed to require pycodestyle 2.3.0 but running pip install -r requirements-dev.txt left mine at 2.2.0, which was breaking flake8. So for now I've just added pycodestyle==2.3.0 to our dev requirements.

  • It seems DRF has a whole fancy filtering system. Reworking our APIs to use this could make it so that DRF's AutoSchema automatically pulls querystring arg docs by introspecting our code, rather than requiring us to manually define fields as I'm doing in this PR. This would help keep our code nice and DRY.

  • As far as I can tell, it doesn't seem like coreapi / the auto-generated documentation provides any way to tell readers about the kind of data that an API endpoint returns, which is a bummer. Although that said, it seems like a third-party library called drf-yasg does provide response schemas, so in the future we could use that, maybe...

  • I am not a big fan of how DRF is auto-naming all our GET methods "list", and using that as the heading for our INTERACT modals, but I can't figure out if there's a way to change that default.

To do

(Moved all of these to #1802.)

toolness added some commits Apr 18, 2018

@toolness toolness requested a review from jseppi Apr 18, 2018

@toolness

This comment has been minimized.

Contributor

toolness commented Apr 18, 2018

@jseppi what do you think of this jibberjabber so far? I feel like we could just merge it as-is and then improve it through subsequent PRs...

@toolness toolness changed the title from Attempt to document API via Django REST Framework to Attempt to document API via Django REST Framework / Core API Apr 18, 2018

@jseppi

jseppi approved these changes Apr 19, 2018

Nice! Definitely seems like a good start!

Do these special DRF docstrings help with the “list” naming: http://www.django-rest-framework.org/topics/documenting-your-api/#documenting-your-views ?

@@ -5,6 +5,7 @@
bandit>=1.0,<2.0
pyflakes==1.6.0
flake8==3.5.0

This comment has been minimized.

@jseppi

jseppi Apr 19, 2018

Contributor

Weird that this is required. I just upgraded our flake8 and pyflakes versions and didn’t see any warnings when I did that...or maybe I just missed them? 🤷‍♂️ Doesn’t really matter though.

This comment has been minimized.

@toolness

toolness Apr 19, 2018

Contributor

Yeah, something might just be messed up with my local configuration. I am confused.

Merge pull request #1801 from 18F/friendlier-flake8
General improvements to linting/testing
@toolness

This comment has been minimized.

Contributor

toolness commented Apr 19, 2018

Woot thanks! I don't think the funky special DRF docstrings help--they're just useful if our view class supports more than one HTTP method, but I don't think they can be used to change the name of the verb, as far as I can tell.

@toolness toolness merged commit 8052679 into develop Apr 19, 2018

3 checks passed

ci/circleci: build Your tests passed on CircleCI!
Details
codeclimate 3 fixed issues
Details
codeclimate/total-coverage 92% (0.0% change)
Details

@toolness toolness deleted the document-api branch Apr 19, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment