CBV docs, fixes #178

Author: masci

docs/views/class_based.rst

@@ -1,3 +1,58 @@
 Class-based Views
 =================
 
+Django OAuth Toolkit provides generic classes useful to implement OAuth2 protected endpoints
+using the *Class Based View* approach.
+
+
+.. class:: ProtectedResourceView(ProtectedResourceMixin, View):
+
+    A view that provides OAuth2 authentication out of the box. To implement a protected
+    endpoint, just define your CBV as::
+
+        class MyEndpoint(ProtectedResourceView):
+            """
+            A GET endpoint that needs OAuth2 authentication
+            """
+            def get(self, request, *args, **kwargs):
+                return HttpResponse('Hello, World!')
+
+    **Please notice**: ``OPTION`` method is not OAuth2 protected to allow preflight requests.
+
+.. class:: ScopedProtectedResourceView(ScopedResourceMixin, ProtectedResourceView):
+
+    A view that provides OAuth2 authentication and scopes handling out of the box. To implement
+    a protected endpoint, just define your CBV specifying the ``required_scopes`` field::
+
+        class MyScopedEndpoint(ScopedProtectedResourceView):
+            required_scopes = ['can_make_it can_break_it']
+
+            """
+            A GET endpoint that needs OAuth2 authentication
+            and a set of scopes: 'can_make_it' and 'can_break_it'
+            """
+            def get(self, request, *args, **kwargs):
+                return HttpResponse('Hello, World!')
+
+
+.. class:: ReadWriteScopedResourceView(ReadWriteScopedResourceMixin, ProtectedResourceView):
+
+    A view that provides OAuth2 authentication and read/write default scopes.
+    ``GET``, ``HEAD``, ``OPTIONS`` http methods require ``read`` scope, others methods
+    need the ``write`` scope. If you need, you can always specify an additional list of
+    scopes in the ``required_scopes`` field::
+
+        class MyRWEndpoint(ReadWriteScopedResourceView):
+            required_scopes = ['has_additional_powers']  # optional
+
+            """
+            A GET endpoint that needs OAuth2 authentication
+            and the 'read' scope. If required_scopes was specified,
+            clients also need those scopes.
+            """
+            def get(self, request, *args, **kwargs):
+                return HttpResponse('Hello, World!')
+
+
+Generic views in DOT are obtained composing a set of mixins you can find in the :doc:`views.mixins <mixins>`
+module: feel free to use those mixins directly if you want to provide your own class based views.

docs/views/mixins.rst

@@ -0,0 +1,5 @@
+Mixins for Class Based Views
+============================
+
+.. automodule:: oauth2_provider.views.mixins
+   :members:

docs/views/views.rst

@@ -9,3 +9,4 @@ Django OAuth Toolkit provides a set of pre-defined views for different purposes:
    function_based
    class_based
    application
+   mixins