feat: add auth to openapi

Author: veloii

.env

@@ -1,4 +1,4 @@
-NEXT_PUBLIC_PROXY_URL=http://localhost:8787
+NEXT_PUBLIC_PROXY_URL=https://classcharts-proxy.veloi.workers.dev
 NEXT_PUBLIC_ALGOLIA_APP_ID=L0EAOEJCCQ
 NEXT_PUBLIC_ALGOLIA_INDEX=docs_index
 NEXT_PUBLIC_ALGOLIA_API_KEY=30fe2c1027197e7f8df72f43f2c655ea

content/docs/authentication.mdx

@@ -27,7 +27,7 @@ You'll need to login first, you can do this through the `/login` endpoint for yo
 
 With each request you must specify your authentication token in the `authorization` header, and optionally your student ID in the URL. However, it is **required** to specify student ID when using the parent API, as ClassCharts needs to know which student you would like to get data for.
 
-E.g. `/apiv2student/activity/2339528` with the header: `Authorization: Basic 5vf2v7n5uk9jftrxaarrik39vk6yjm48`.
+E.g. `/apiv2student/activity/2339528` with the header: `Authorization: Basic eW91IHNob3VsZCBzdGFyIHRoaXMgcmVwbyE`.
 
 ## Retaining a session
 

content/docs/parent-api/ping.mdx

@@ -2,14 +2,9 @@
 title: Parent Ping
 description: >
   Gets basic information about the logged in parent and what access they have.  
+
   This endpoint is also used for revalidating your session id (authentication
   token).
-
-  To get your new authentication token, call the endpoint, and use the token in
-  the returned body (`body.meta.session_id`) as your new authentication token.
-
-
-  Access tokens should be refreshed every 180 seconds.
 full: true
 _openapi:
   method: POST
@@ -20,15 +15,10 @@ _openapi:
     contents:
       - content: >
           Gets basic information about the logged in parent and what access they
-          have.   This endpoint is also used for revalidating your session id
-          (authentication token).
-
-          To get your new authentication token, call the endpoint, and use the
-          token in the returned body (`body.meta.session_id`) as your new
-          authentication token.
+          have.  
 
-
-          Access tokens should be refreshed every 180 seconds.
+          This endpoint is also used for revalidating your session id
+          (authentication token).
 ---
 
 <APIPage document={"./openapi/parentclientapi.yaml"} operations={[{"path":"/ping","method":"post"}]} hasHead={false} />

openapi/clientapi.yaml

@@ -9,11 +9,18 @@ servers:
   - url: https://www.classcharts.com/apiv2parent
     description: Parent API
 
+components:
+  securitySchemes:
+    basic_auth:
+      $ref: "./schemas/auth/basic_auth.yaml#/basic_auth"
+
 paths:
   /behaviour/{studentId}:
     get:
       operationId: list-behaviour
       summary: List Behaviour
+      security:
+        - basic_auth: []
       description: Gets the student's behaviour.
       parameters:
         - name: studentId
@@ -62,6 +69,8 @@ paths:
     get:
       operationId: list-activity
       summary: List Activity
+      security:
+        - basic_auth: []
       description: >
         The `from` field does not work as you would expect, since this endpoint is meant for pagination on the home page, Classcharts only returns a 50 points from the `to` field.
 
@@ -120,6 +129,8 @@ paths:
       operationId: list-homeworks
       summary: List Homeworks
       description: Gets the student's homeworks
+      security:
+        - basic_auth: []
 
       parameters:
         - name: studentId
@@ -178,6 +189,8 @@ paths:
       operationId: list-classes
       summary: List Classes
       description: Lists the student's classes
+      security:
+        - basic_auth: []
       parameters:
         - name: studentId
           in: path
@@ -203,6 +216,8 @@ paths:
       operationId: list-lessons
       summary: List Lessons
       description: Gets the student's lessons for a given date
+      security:
+        - basic_auth: []
       parameters:
         - name: studentId
           in: path
@@ -246,6 +261,8 @@ paths:
       operationId: list-badges
       summary: List Badges
       description: Gets the student's earned badges
+      security:
+        - basic_auth: []
       parameters:
         - name: studentId
           in: path
@@ -281,6 +298,8 @@ paths:
       operationId: list-announcements
       summary: List Announcements
       description: Gets the student's announcements
+      security:
+        - basic_auth: []
       parameters:
         - name: studentId
           in: path
@@ -316,6 +335,8 @@ paths:
       operationId: list-detentions
       summary: List Detentions
       description: Gets the student's detentions
+      security:
+        - basic_auth: []
       parameters:
         - name: studentId
           in: path
@@ -351,6 +372,8 @@ paths:
       operationId: get-attendance
       summary: List Attendance
       description: Gets the student's attendance
+      security:
+        - basic_auth: []
       parameters:
         - name: studentId
           in: path
@@ -396,6 +419,8 @@ paths:
       operationId: list-pupil-fields
       summary: List Pupil Fields
       description: Gets the student's pupil fields
+      security:
+        - basic_auth: []
       parameters:
         - name: studentId
           in: path
@@ -431,6 +456,8 @@ paths:
       operationId: list-academic-reports
       summary: List Academic Reports
       description: Get list of academic reports
+      security:
+        - basic_auth: []
       parameters:
         - name: studentId
           in: query
@@ -456,6 +483,8 @@ paths:
       operationId: get-academic-report
       summary: Get Academic Report
       description: Get academic report by ID
+      security:
+        - basic_auth: []
       parameters:
         - name: studentId
           in: query
@@ -487,6 +516,8 @@ paths:
       operationId: list-on-report-cards
       summary: List On Report Cards
       description: Get list of on report cards
+      security:
+        - basic_auth: []
       parameters:
         - name: pupil_id
           in: query
@@ -511,6 +542,8 @@ paths:
       operationId: get-on-report-card
       summary: Get On Report Card
       description: Get on report card by ID
+      security:
+        - basic_auth: []
       parameters:
         - name: pupil_id
           in: query
@@ -542,6 +575,8 @@ paths:
       operationId: get-on-report-card-summary-comment
       summary: Get On Report Card Summary Comment
       description: Get on report card summary comment by date
+      security:
+        - basic_auth: []
       parameters:
         - name: pupil_id
           in: query
@@ -577,6 +612,8 @@ paths:
       operationId: get-on-report-card-target
       summary: Get On Report Card Target
       description: Get on report card target
+      security:
+        - basic_auth: []
       parameters:
         - name: pupil_id
           in: query

openapi/parentclientapi.yaml

@@ -7,19 +7,22 @@ servers:
   - url: https://www.classcharts.com/apiv2parent
     description: Parent API
 
+components:
+  securitySchemes:
+    basic_auth:
+      $ref: "./schemas/auth/basic_auth.yaml#/basic_auth"
+
 paths:
   /ping:
     post:
       operationId: ping
       summary: Parent Ping
       description: >
         Gets basic information about the logged in parent and what access they have.  
-        This endpoint is also used for revalidating your session id (authentication token).
-
-        To get your new authentication token, call the endpoint, and use the token in the returned body (`body.meta.session_id`) as your new authentication token.
 
-
-        Access tokens should be refreshed every 180 seconds.
+        This endpoint is also used for revalidating your session id (authentication token).
+      security:
+        - basic_auth: []
 
       requestBody:
         content:
@@ -55,6 +58,8 @@ paths:
       operationId: list-pupils
       summary: List Pupils
       description: Get a list of pupils connected to this parent's account
+      security:
+        - basic_auth: []
       responses:
         "200":
           description: Array of pupils
@@ -85,6 +90,8 @@ paths:
       summary: List Parent Behaviour
       description: >
         Lists the behaviour points for a pupil.
+      security:
+        - basic_auth: []
       parameters:
         - name: studentId
           in: path
@@ -111,6 +118,8 @@ paths:
       summary: Delete Parent Behaviour Point
       description: >
         Delets a behaviour point from a pupil's record.
+      security:
+        - basic_auth: []
       requestBody:
         required: true
         content:
@@ -143,6 +152,8 @@ paths:
       summary: Add Parent Behaviour Point
       description: >
         Adds a behaviour point to a pupil's record.
+      security:
+        - basic_auth: []
       requestBody:
         required: true
         content:
@@ -205,6 +216,8 @@ paths:
       operationId: change-password
       summary: Change Password
       description: Changes the login password for the current parent account
+      security:
+        - basic_auth: []
       requestBody:
         required: true
         content:

openapi/schemas/auth/basic_auth.yaml

@@ -0,0 +1,5 @@
+basic_auth:
+  type: http
+  scheme: basic
+  description: >
+    This is the `session_id` returned when logging in. e.g. `Basic eW91IHNob3VsZCBzdGFyIHRoaXMgcmVwbyE=`

openapi/studentclientapi.yaml

@@ -7,6 +7,11 @@ servers:
   - url: https://www.classcharts.com/apiv2student
     description: Student API
 
+components:
+  securitySchemes:
+    basic_auth:
+      $ref: "./schemas/auth/basic_auth.yaml#/basic_auth"
+
 paths:
   /ping:
     post:
@@ -16,6 +21,8 @@ paths:
         Gets basic information about the logged in student and what access they have.  
 
         This endpoint is also used for revalidating your session id (authentication token).
+      security:
+        - basic_auth: []
 
       requestBody:
         content:
@@ -78,6 +85,8 @@ paths:
       operationId: list-rewards
       summary: List Rewards
       description: Gets the available items in the student's rewards shop.
+      security:
+        - basic_auth: []
       parameters:
         - name: studentId
           in: path
@@ -113,6 +122,8 @@ paths:
       operationId: purchase-reward
       summary: Purchase Reward
       description: Purchase a reward item from the student's rewards shop.
+      security:
+        - basic_auth: []
       parameters:
         - name: itemId
           in: path
@@ -157,6 +168,8 @@ paths:
       operationId: tick-homework
       summary: Tick Homework
       description: Toggle the status of a homework item to 'completed'.
+      security:
+        - basic_auth: []
 
       parameters:
         - name: studentId
@@ -190,6 +203,8 @@ paths:
       operationId: get-student-code
       summary: Get Student Code
       description: Gets the student's student code
+      security:
+        - basic_auth: []
       requestBody:
         required: true
         content: