From 40bd435c224bb198a829fc0c5b7c66c2859b6753 Mon Sep 17 00:00:00 2001
From: guille <guillermo.gutierrezmorote@concordia.ca>
Date: Tue, 14 Feb 2023 05:37:59 -0500
Subject: [PATCH] Complete the session deffinitions in the yml file.

---
 hub_api/docs/openapi-specs.yml | 145 +++++++++++++++++++++++++++++----
 hub_api/session.py             |   4 +-
 2 files changed, 131 insertions(+), 18 deletions(-)

diff --git a/hub_api/docs/openapi-specs.yml b/hub_api/docs/openapi-specs.yml
index 03cf72f..f953fed 100644
--- a/hub_api/docs/openapi-specs.yml
+++ b/hub_api/docs/openapi-specs.yml
@@ -50,14 +50,119 @@ paths:
         - Session start
       summary: Starts an user session
       operationId: session_start
-      description: Authenticate and initialize an user session in the api
+      description: Authentication and initialisation of a user session in the Api
       responses:
         '200':
-          description: Authorized
+          description: Succeed
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/authorized'
+                $ref: '#/components/schemas/succeed'
+          headers:
+            token:
+              type: string
+              format: uuid
+              description: Token expected in next operation header
+              example: '77e1c83b-7bb0-437b-bc50-a7a58e5660ac'
+        '403':
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/unauthorized'
+  /v1.4/session/keep_alive:
+    put:
+      security:
+        - session_id: []
+        - token: []
+        - application_id: []
+      parameters:
+        - in: header
+          name: session_id
+          schema:
+            type: string
+          required: true
+          description: the Id of the current session
+        - in: header
+          name: token
+          schema:
+            type: string
+          required: true
+          description: the last token received from the API
+        - in: header
+          name: application_id
+          schema:
+            type: string
+          required: true
+          description: the Id of the application accessing this API
+
+      tags:
+        - Keep alive
+      summary: Keep the current user session alive
+      operationId: keep_alive
+      description: Refresh and keep the current session alive and renew the token
+      responses:
+        '200':
+          description: Succeed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/succeed'
+          headers:
+            token:
+              type: string
+              format: uuid
+              description: Token expected in next operation header
+              example: '77e1c83b-7bb0-437b-bc50-a7a58e5660ac'
+        '403':
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/unauthorized'
+  /v1.4/session/end:
+    put:
+      security:
+        - session_id: []
+        - token: []
+        - application_id: []
+      parameters:
+        - in: header
+          name: session_id
+          schema:
+            type: string
+          required: true
+          description: the Id of the current session
+        - in: header
+          name: token
+          schema:
+            type: string
+          required: true
+          description: the last token received from the API
+        - in: header
+          name: application_id
+          schema:
+            type: string
+          required: true
+          description: the Id of the application accessing this API
+      tags:
+        - End session
+      summary: Ends the current user session
+      operationId: session_end
+      description: End the current user session and free the alocated resources
+      responses:
+        '200':
+          description: Succeed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/succeed'
+          headers:
+            token:
+              type: string
+              format: uuid
+              description: Token expected in next operation header
+              example: '77e1c83b-7bb0-437b-bc50-a7a58e5660ac'
         '403':
           description: Unauthorized
           content:
@@ -65,6 +170,19 @@ paths:
               schema:
                 $ref: '#/components/schemas/unauthorized'
 components:
+  securitySchemes:
+    session_id:
+      type: apiKey
+      in: header
+      name: session_id
+    application_id:
+      type: apiKey
+      in: header
+      name: application_id
+    token:
+      type: apiKey
+      in: header
+      name: token
   schemas:
     uptime:
       type: object
@@ -72,21 +190,16 @@ components:
         uptime:
           type: string
           format: hh:mm:ss.ms
-          example: "00:09:53.600281"
-    authorized:
-      type: object
-      properties:
-        session_id:
-          type: string
-          format: uuid
-          example: "ad0720ed-0f31-4f3e-9686-1177d4624ec1"
-        token:
-          type: string
-          format: uuid
-          example: "660d1aa0-d24f-4cb1-902d-13c7bd29793c"
+          example: '00:09:53.600281'
     unauthorized:
       type: object
       properties:
         error:
           type: string
-          example: "unauthorized"
\ No newline at end of file
+          example: 'unauthorized'
+    succeed:
+      type: object
+      properties:
+        succeed:
+          type: string
+          example: 'OK'
\ No newline at end of file
diff --git a/hub_api/session.py b/hub_api/session.py
index e7bf0c6..6364c43 100644
--- a/hub_api/session.py
+++ b/hub_api/session.py
@@ -54,7 +54,7 @@ class SessionEnd(Resource):
   def put():
     if remove_session(request):
       return Response(json.dumps({'result': 'succeed'}))
-    return Response(json.dumps({'error': 'invalid session'}), status=401)
+    return Response(json.dumps({'error': 'unauthorized'}), status=403)
 
 class KeepSessionAlive(Resource):
   def __init__(self):
@@ -64,7 +64,7 @@ class KeepSessionAlive(Resource):
   def put():
     session = refresh_session(request)
     if session is None:
-      return Response(json.dumps({'error': 'invalid session'}), status=401)
+      return Response(json.dumps({'error': 'unauthorized'}), status=403)
     headers = session.headers
     response = {'result': 'succeed'}
     return Response(json.dumps(response), headers=headers)