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

Improve API docs #1811

Merged
merged 9 commits into from Apr 20, 2018

Conversation

Projects
None yet
2 participants
@toolness
Contributor

toolness commented Apr 19, 2018

This fixes #1802 by making the following improvements to our API documentation:

  • /api/, which previously 404'd, now redirects to /api/docs/. I didn't want to move the docs endpoint to /api/ because I think it could be useful in the future to have DRF's funky router root thingy at /api/.
  • Querystring argument docs can now contain markdown. We mostly use this for monospaced text that reflects argument values, but we also use it for a few lists.
  • It clarifies vaguely-documented querystring parameters for our API endpoints (mostly by lifting documentation from api.md).
  • It documents the sin querystring argument, which wasn't previously documented.
  • api.md has been removed; the "API" link from the developer documentation TOC now goes to /api/docs/.
  • The intro from api.md has been moved to the top of /api/docs/, and also includes a link back to /docs/, so that both sets of documentation link to each other.
  • The header of CALC's browsable API (e.g. when one visits /api/rates/ in a browser) has been customized to display "CALC API" instead of "Django REST Framework". Clicking on this link now takes readers to /api/docs/.

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

@toolness toolness referenced this pull request Apr 19, 2018

Closed

General improvements to API documentation #1802

5 of 5 tasks complete

toolness added some commits Apr 19, 2018

@jseppi

jseppi approved these changes Apr 20, 2018

Nice, looks great!

@toolness toolness merged commit b5c701e into develop Apr 20, 2018

3 checks passed

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

@toolness toolness deleted the better-api-docs branch Apr 20, 2018

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