Merge pull request #131 from eduNEXT/mgs/grade-api-docs

Add documentation for the Grades API.

Author: MoisesGSalas

CHANGELOG.rst

@@ -11,6 +11,9 @@ Change Log
 .. There should always be an "Unreleased" section for changes pending release.
 Unreleased
 ----------
+Added
+~~~~~
+* New Grades API to retrieve grades from a single user on a course.
 
 [4.0.0] - 2021-1-20
 --------------------

eox_core/api/v1/serializers.py

@@ -257,7 +257,7 @@ class EdxappGradingPolicySerializer(serializers.Serializer):
     """
     Serializes the course grading policy
     """
-    grader = EdxappGradingRawPolicySerializer(many=True, required=False, source="GRADER")
+    grader = EdxappGradingRawPolicySerializer(many=True, source="GRADER")
     grade_cutoffs = serializers.DictField(child=serializers.FloatField(), source="GRADE_CUTOFFS")
 
 
@@ -268,3 +268,37 @@ class EdxappGradeSerializer(serializers.Serializer):
     earned_grade = serializers.FloatField()
     grading_policy = EdxappGradingPolicySerializer(required=False)
     section_breakdown = EdxappSectionBreakdownSerializer(many=True, required=False)
+
+    class Meta:
+        """
+        Add extra details for swagger
+        """
+        swagger_schema_fields = {
+            "example":
+            {
+                "earned_grade": 0.5,
+                "grading_policy": {
+                    "grader": [
+                        {
+                            "assignment_type": "Homework",
+                            "count": 1,
+                            "dropped": 0,
+                            "weight": 1.0
+                        }
+                    ],
+                    "grade_cutoffs": {
+                        "Pass": 0.5
+                    }
+                },
+                "section_breakdown": [
+                    {
+                        "attempted": True,
+                        "assignment_type": "Homework",
+                        "percent": 0.5,
+                        "score_earned": 5,
+                        "score_possible": 10,
+                        "subsection_name": "Homework - Questions"
+                    }
+                ]
+            }
+        }

eox_core/api/v1/tests/test_grades.py

@@ -46,10 +46,6 @@ def test_get_grade_no_detail_no_policy(  # pylint: disable=too-many-arguments
         get_edxapp_user.return_value.username = "test"
         get_enrollment.return_value = None, None
         grade_factory.return_value.return_value.read.return_value.percent = 0.5
-        grade_factory.return_value.return_value.read.return_value.subsection_grades = []
-        get_courseware_courses.return_value.get_course_by_id.return_value.grading_policy = (
-            {}
-        )
         params = {
             "course_id": "course-v1:org+course+run",
             "username": "test",
@@ -116,7 +112,8 @@ def test_get_grade_detail_policy(  # pylint: disable=too-many-arguments
         grade_factory.return_value.return_value.read.return_value.percent = 0.5
         grade_factory.return_value.return_value.read.return_value.subsection_grades = {}
         get_courseware_courses.return_value.get_course_by_id.return_value.grading_policy = {
-            "GRADE_CUTOFFS": {}
+            "GRADE_CUTOFFS": {},
+            "GRADER": [],
         }
         params = {
             "username": "test",
@@ -126,7 +123,7 @@ def test_get_grade_detail_policy(  # pylint: disable=too-many-arguments
         }
         expected_response = {
             "earned_grade": 0.5,
-            "grading_policy": {"grade_cutoffs": {}},
+            "grading_policy": {"grade_cutoffs": {}, "grader": []},
             "section_breakdown": [],
         }
 

eox_core/api/v1/views.py

@@ -695,20 +695,74 @@ class EdxappGrade(UserQueryMixin, APIView):
     permission_classes = (EoxCoreAPIPermission,)
     renderer_classes = (JSONRenderer, BrowsableAPIRenderer)
 
+    @apidocs.schema(
+        parameters=[
+            apidocs.query_parameter(
+                name="username",
+                param_type=str,
+                description="**required**, The username used to identify a user enrolled on the course. Use either username or email.",
+            ),
+            apidocs.query_parameter(
+                name="email",
+                param_type=str,
+                description="**required**, The email used to identify a user enrolled on the course. Use either username or email.",
+            ),
+            apidocs.query_parameter(
+                name="course_id",
+                param_type=str,
+                description="**required**, The course id for the enrollment you want to check.",
+            ),
+            apidocs.query_parameter(
+                name="detailed",
+                param_type=bool,
+                description="**optional**, If true include detailed data for each graded subsection",
+            ),
+            apidocs.query_parameter(
+                name="grading_policy",
+                param_type=bool,
+                description="**optional**, If true include course grading policy.",
+            ),
+        ],
+        responses={
+            200: EdxappGradeSerializer,
+            400: "Bad request, missing course_id or either email or username",
+            404: "User, course or enrollment not found",
+        },
+    )
     def get(self, request):
         """
         Retrieves Grades information for given a user and course_id
 
         **Example Requests**
 
-            GET /eox-core/api/v1/grade/?username=johndoe&
-            course_id=course-v1:edX+DemoX+Demo_Course
+            GET /eox-core/api/v1/grade/?username=johndoe&course_id=course-v1:edX+DemoX+Demo_Course
 
             Request data: {
               "username": "johndoe",
               "course_id": "course-v1:edX+DemoX+Demo_Course",
             }
 
+        **Response details**
+
+        - `earned_grade`: Final user score for the course.
+        - `section_breakdown` (**optional**): Details of each grade subsection.
+            - `attempted`: Whether the learner attempted the assignment.
+            - `assignment_type`: General category of the assignment.
+            - `percent`: Grade obtained by the user on this subsection.
+            - `score_earned`: The score a user earned on this subsection.
+            - `score_possible`: Highest possible score a user can earn on this subsection.
+            - `subsection_name`: Name of the subsection.
+        - `grading_policy` (**optional**): Course grading policy.
+            - `grade_cutoff`: Score needed to reach each grade.
+            - `grader`: Details of each assignment type used by the Grader.
+                - `assignment_type`: General category of the assignment.
+                - `count`: Number of assignments of this type.
+                - `dropped`: The number of assignments of this type that the grader will drop. The grader will drop the lowest-scored assignments first.
+                - `weight`: Weight of this type of assignment towards the final grade.
+
+        More information about grading can be found in the
+        [edX documentation](https://edx.readthedocs.io/projects/open-edx-building-and-running-a-course/en/latest/student_progress/course_grades.html).
+
         **Returns**
 
         - 200: Success.