Enable the Django Rest Framework built-in documentation feature #1832
Conversation
reupen
force-pushed
the
feature/api-docs
branch
2 times, most recently
from
bc9baf8 to
2551ca8
Compare
Codecov Report
@@ Coverage Diff @@
## develop #1832 +/- ##
===========================================
+ Coverage 97.24% 97.24% +<.01%
===========================================
Files 308 308
Lines 9616 9629 +13
Branches 981 982 +1
===========================================
+ Hits 9351 9364 +13
Misses 181 181
Partials 84 84
Continue to review full report at Codecov.
|
You can have a look at it looks like in DRF 3.10 via the docs on their master branch:
They seem to be in the process of releasing DRF 3.10.0 right now so it shouldn't be far off at all (but we will need an update to django-filter as well for carltongibson/django-filter#1086). |
| """Base matching information APIView.""" | ||
|
|
||
| required_scopes = (Scope.internal_front_end,) | ||
|
|
||
| queryset = Company.objects.select_related('dnbmatchingresult') | ||
|
|
||
| lookup_url_kwarg = 'company_pk' | ||
| def _get_company(self): |
There was a problem hiding this comment.
Can we please pass down self.kwargs['company_pk'] as an argument to this method? The same for _get_matching_information. I don't think utility functions should concern themselves with the existence of self.kwargs['company_pk'].
There was a problem hiding this comment.
I'll change _get_matching_information() to take a company as that one does seem a bit weird.
However, I think _get_company() fits in with how get_object() works in generic views and it would be a bit repetitive if we started writing self.kwargs['company_pk'] everywhere.
This is to make views compatible with DRF schema introspection.
This is because they aren't actually generic views, and inheriting from GenericAPIView breaks DRF schema introspection.
This refactors the views slightly so that `Http404`s are not raised when building serializer contexts if the order referenced in the URL path does not exist (which breaks DRF schema introspection). Instead, this is checked as part of the request dispatch process (which seems like a more logical place to do this kind of check).
This enables the Django Rest Framework built-in documentation feature at the URL path `/docs`. This is currently only enabled if the `ENABLE_API_DOCUMENTATION` environment variable is set to `True` as the documentation is not fully functional as yet. A user must log into Django admin prior to accessing the documentation. The DRF 3.9 will move more to OpenAPI-based schema generation and these changes will help us to start using that when we upgrade.
Description of change
This enables the Django Rest Framework built-in documentation feature at the URL path
/docs.This is currently only enabled if the
ENABLE_API_DOCUMENTATIONenvironment variable is set toTrueas the documentation is not fully functional as yet.Currently, a user must log into Django admin prior to accessing the documentation.
Some minor changes had to be made to a few views in order to get the view introspection working. (In the case of the D&B views, they were not really generic views and so have been changed to use APIView instead of GenericAPIView.)
The next version of DRF moves more towards OpenAPI-based schema generation and these changes will help us in switching to that when we upgrade.
I'm planning to fix a few things in further PRs, and then will probably enable the docs by default for (at least) local and the dev environments. Will also add some docs to make it clear what needs to be done for new endpoints.
Screenshots
These show the docs functionality in DRF 3.9 (this may change when we upgrade to 3.10).
Checklist
fixtures/test_data.yaml) been updated?