Add docs for RequestMetricsMiddleware.

ARCH-220
openedx · Aug 17, 2018 · 0dd7732 · 0dd7732
1 parent 6a148c6
commit 0dd7732
Show file tree

Hide file tree

Showing 5 changed files with 29 additions and 2 deletions.
diff --git a/AUTHORS b/AUTHORS
@@ -1,3 +1,4 @@
 Clinton Blackburn <cblackburn@edx.org>
 Bill DeRusha <bill@edx.org>
 Jeremy Bowman <jbowman@edx.org>
+Robert Raposa <rraposa@edx.org>
diff --git a/docs/index.rst b/docs/index.rst
@@ -30,5 +30,6 @@ Table of Contents
 
     settings
     authentication
+    middleware
     permissions
     utils
diff --git a/docs/middleware.rst b/docs/middleware.rst
@@ -0,0 +1,6 @@
+Middleware
+==========
+This module contains middleware to ensure best practices of DRF and other endpoints..
+
+.. automodule:: edx_rest_framework_extensions.middleware
+    :members:
diff --git a/edx_rest_framework_extensions/__init__.py b/edx_rest_framework_extensions/__init__.py
@@ -1,3 +1,3 @@
 """ edx Django REST Framework extensions. """
 
-__version__ = '1.6.1'  # pragma: no cover
+__version__ = '1.6.2'  # pragma: no cover
diff --git a/edx_rest_framework_extensions/middleware.py b/edx_rest_framework_extensions/middleware.py
@@ -1,5 +1,5 @@
 """
-Middleware to ensure best practices of DRF endpoints.
+Middleware to ensure best practices of DRF and other endpoints.
 """
 import logging
 
@@ -76,6 +76,25 @@ def process_view(self, request, view_func, view_args, view_kwargs):  # pylint: d
 class RequestMetricsMiddleware(object):
     """
     Adds various request related metrics.
+
+    Possible metrics include:
+        request_auth_type: Example values include: no-user, unauthenticated,
+            jwt, bearer, other-token-type, or session-or-unknown
+        request_user_agent: The user agent string from the request header.
+        request_client_name: The client name from edx-rest-api-client calls.
+        request_referer
+
+    This middleware is dependent on the RequestCacheMiddleware. You must
+    include this middleware later.  For example::
+
+        MIDDLEWARE_CLASSES = (
+            'edx_django_utils.cache.middleware.RequestCacheMiddleware',
+            'edx_rest_framework_extensions.middleware.RequestMetricsMiddleware',
+        )
+
+    TODO: Make edx-django-utils _check_middleware_dependencies public and use
+    it here. See https://github.com/edx/edx-django-utils/blob/e45137359c85f36f4f7495725c48e4af1146fe5a/edx_django_utils/private_utils.py#L12
+
     """
 
     def process_response(self, request, response):