feat: added doc for upcoming endpoints to finish up entrepreneur join, response codes remaining to update

documentation/openapi/src/adminApi.yaml

@@ -8,7 +8,7 @@ paths:
         - Admin API
       security:
         - MyINPulse: [MyINPulse-admin]
-      description: Retrieves a list of projects managed by the requesting admin, including key details for overview.
+      description: Retrieves a list of projects managed by the requesting admin, including details for overview.
       responses:
         "200":
           description: OK - List of projects returned successfully.
@@ -26,7 +26,7 @@ paths:
     post:
       operationId: addProjectManually
       summary: Manually add a new project
-      description: Creates a new project with the provided details. 
+      description: Creates a new project with the provided details. (NOTE that this meant for manually inserting projects, for example importing already existing projects).
       tags:
         - Admin API
       security:
@@ -72,6 +72,58 @@ paths:
         "401":
           description: Unauthorized.        
 
+  /admin/request-join:
+    get:
+      operationId: getPendingProjects
+      summary: Get entrepreneurs project join requests
+      tags:
+        - Admin API
+      security:
+        - MyINPulse: [MyINPulse-admin]
+      description:  Retrieves a list of pending requests from entrepreneurs to join an existing project.
+      responses:
+        "200":
+          description: OK - List of pending project join requests.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "./main.yaml#/components/schemas/joinRequest"
+        "401":
+          description: Unauthorized.
+  
+  /admin/request-join/decision/{joinRequestId}:
+    post:
+      summary: Approve or reject a pending project join request
+      tags:
+        - Admin API
+      security:
+        - MyINPulse: [MyINPulse-admin]
+      parameters:
+        - in: path
+          name: joinRequestId
+          required: true
+          schema:
+            type: integer
+          description: The ID of the pending join request to decide upon.
+        
+      description: |-
+        Allows an admin to make a decision on an ebtrepreneur's request to join an existing project awaiting validation.
+        If approved (isAccepted=true), the entrepreneur is linked to the project with ID joinRequestId.
+        If rejected (isAccepted=false), the pending request data might be archived or deleted based on business logic.
+      responses:
+        "200":
+          description: OK - No Content, decision processed successfully..
+          content:
+            application/json:
+              $ref: "./main.yaml#/components/schemas/joinRequestDecision"
+        "400":
+          description: Bad Request - Invalid input (e.g., missing decision).
+        "401":
+          description: Unauthorized.     
+
+
   /admin/projects/pending/decision/{pendingProjectId}:
     post:
       operationId: decidePendingProject
@@ -80,8 +132,8 @@ paths:
         - Admin API
       description: |-
         Allows an admin to make a decision on a project awaiting validation.
-        If approved (decision=true), the project status changes, and it's linked to the involved users.
+        If approved (isAccepted=true), the project status changes, and it's linked to the involved users.
-        If rejected (decision=false), the pending project data might be archived or deleted based on business logic.
+        If rejected (isAccepted=false), the pending project data might be archived or deleted based on business logic.
       security:
           - MyINPulse: [MyINPulse-admin]
       parameters:

documentation/openapi/src/bundled.yaml

@@ -99,7 +99,7 @@ components:
           type: string
           format: date
           description: The date when this cell was last modified.
-          example: '2025-04-15'
+          example: 'yyyy-MM-dd HH:mm'
     project:
       type: object
       description: Represents a project being managed or developed.
@@ -116,7 +116,7 @@ components:
           type: string
           format: date
           description: The date when the project was created in the system.
-          example: '2024-11-20'
+          example: 'yyyy-MM-dd HH:mm'
         logo:
           type: string
           format: byte
@@ -176,12 +176,14 @@ components:
           example: Q3 Roadmap Planning
     joinRequest:
       type: object
-      description: Represents a request from an entrepreneur to join an existing project.
+      description: Represents a request from an entrepreneur to join an already existing project.
       properties:
-        projectId:
+        idProject:
           type: integer
-          description: The ID of the project the entrepreneur wants to join.
+          description: the ID of the project the entrepreneur wants to join.
-          example: 12
+          example: 42
+        entrepreneur:
+          $ref: '#/components/schemas/user-entrepreneur'
     projectDecision:
       type: object
       description: Represents a decision from an admin to accept a pending project.
@@ -198,6 +200,14 @@ components:
           type: boolean
           description: The boolean value of the decision.
           example: 'true'
+    joinRequestDecision:
+      type: object
+      description: Represents a decision from an admin to accept a pending project join request.
+      properties:
+        isAccepted:
+          type: boolean
+          description: The boolean value of the decision.
+          example: 'true'
   securitySchemes:
     MyINPulse:
       type: oauth2
@@ -210,7 +220,7 @@ components:
             MyINPulse-entrepreneur: Grants standard entrepreneur user access.
 servers:
   - url: '{serverProtocol}://{serverHost}:{serverPort}'
-    description: API Server Environment
+    description: API Server
     variables:
       serverProtocol:
         enum:
@@ -314,6 +324,56 @@ paths:
           description: Bad Request - Invalid user ID format.
         '401':
           description: Unauthorized.
+  /admin/request-join:
+    get:
+      operationId: getPendingProjects
+      summary: Get entrepreneurs project join requests
+      tags:
+        - Admin API
+      security:
+        - MyINPulse:
+            - MyINPulse-admin
+      description: Retrieves a list of pending requests from entrepreneurs to join an existing project.
+      responses:
+        '200':
+          description: OK - List of pending project join requests.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/joinRequest'
+        '401':
+          description: Unauthorized.
+  '/admin/request-join/decision/{joinRequestId}':
+    post:
+      summary: Approve or reject a pending project join request
+      tags:
+        - Admin API
+      security:
+        - MyINPulse:
+            - MyINPulse-admin
+      parameters:
+        - in: path
+          name: joinRequestId
+          required: true
+          schema:
+            type: integer
+          description: The ID of the pending join request to decide upon.
+      description: |-
+        Allows an admin to make a decision on an ebtrepreneur's request to join an existing project awaiting validation.
+        If approved (isAccepted=true), the entrepreneur is linked to the project with ID joinRequestId.
+        If rejected (isAccepted=false), the pending request data might be archived or deleted based on business logic.
+      responses:
+        '200':
+          description: 'OK - No Content, decision processed successfully..'
+          content:
+            application/json:
+              $ref: '#/components/schemas/joinRequestDecision'
+        '400':
+          description: 'Bad Request - Invalid input (e.g., missing decision).'
+        '401':
+          description: Unauthorized.
   /admin/projects:
     get:
       operationId: getAdminProjects
@@ -323,7 +383,7 @@ paths:
       security:
         - MyINPulse:
             - MyINPulse-admin
-      description: 'Retrieves a list of projects managed by the requesting admin, including key details for overview.'
+      description: 'Retrieves a list of projects managed by the requesting admin, including details for overview.'
       responses:
         '200':
           description: OK - List of projects returned successfully.
@@ -340,7 +400,7 @@ paths:
     post:
       operationId: addProjectManually
       summary: Manually add a new project
-      description: Creates a new project with the provided details.
+      description: 'Creates a new project with the provided details. (NOTE that this meant for manually inserting projects, for example importing already existing projects).'
       tags:
         - Admin API
       security:
@@ -393,8 +453,8 @@ paths:
         - Admin API
       description: |-
         Allows an admin to make a decision on a project awaiting validation.
-        If approved (decision=true), the project status changes, and it's linked to the involved users.
+        If approved (isAccepted=true), the project status changes, and it's linked to the involved users.
-        If rejected (decision=false), the pending project data might be archived or deleted based on business logic.
+        If rejected (isAccepted=false), the pending project data might be archived or deleted based on business logic.
       security:
         - MyINPulse:
             - MyINPulse-admin
@@ -593,7 +653,7 @@ paths:
           schema:
             type: string
             format: date
-          description: The modification date to filter by (YYYY-MM-DD).
+          description: 'The modification date to filter by (YYYY-MM-DD HH:mm).'
       responses:
         '200':
           description: OK - List of section cells matching the criteria.
@@ -642,8 +702,8 @@ paths:
           description: Not Found - Project not found.
   '/shared/projects/admin/{projectId}':
     get:
-      operationId: getProjectAdmins
+      operationId: getProjectAdmin
-      summary: Get admins associated with a project
+      summary: Get admin associated with a project
       tags:
         - Shared API
       security:
@@ -660,7 +720,7 @@ paths:
           description: ID of the project.
       responses:
         '200':
-          description: OK - List of admins.
+          description: OK - admin.
           content:
             application/json:
               schema:
@@ -720,11 +780,13 @@ paths:
           description: ID of the appointment.
       responses:
         '200':
-          description: OK - Report content returned.
+          description: OK - Report PDF returned.
           content:
-            application/json:
+            application/pdf:
               schema:
-                $ref: '#/components/schemas/report'
+                schema: null
+                type: string
+                format: binary
         '401':
           description: Unauthorized.
   /shared/appointments/request:
@@ -818,7 +880,7 @@ paths:
     put:
       operationId: modifySectionCell
       summary: Modify data in a Lean Canvas section cell
-      description: Updates the content of an existing Lean Canvas section cell specified by `sectionCellId`. The server updates the `modificationDate`.
+      description: Updates the content of an existing Lean Canvas section cell specified by `sectionCellId`. The server "updates" (it keeps a record of the previous version to keep a history of all the sectionCells and creates a new ones with the specified modifications) the `modificationDate`.
       tags:
         - Entrepreneurs API
       security:
@@ -834,7 +896,7 @@ paths:
           example: 508
       requestBody:
         required: true
-        description: Updated section cell details. `idSectionCell` should match the path parameter. `modificationDate` will be updated by the server.
+        description: Updated section cell details. `sectionCellId` "the path parameter" is the only id that's consideredn the `sectionCellId` id in the request body is ignored. `modificationDate` should be updated by the server.
         content:
           application/json:
             schema:

documentation/openapi/src/entrepreneurApi.yaml

@@ -57,7 +57,7 @@ paths:
     put:
       operationId: modifySectionCell
       summary: Modify data in a Lean Canvas section cell
-      description: Updates the content of an existing Lean Canvas section cell specified by `sectionCellId`. The server updates the `modificationDate`.
+      description: Updates the content of an existing Lean Canvas section cell specified by `sectionCellId`. The server "updates" (it keeps a record of the previous version to keep a history of all the sectionCells and creates a new ones with the specified modifications) the `modificationDate`.
       tags:
        - Entrepreneurs API
       security:
@@ -72,7 +72,7 @@ paths:
           example: 508
       requestBody:
         required: true
-        description: Updated section cell details. `idSectionCell` should match the path parameter. `modificationDate` will be updated by the server.
+        description: Updated section cell details. `sectionCellId` "the path parameter" is the only id that's consideredn the `sectionCellId` id in the request body is ignored. `modificationDate` should be updated by the server.
         content:
           application/json:
             schema:

documentation/openapi/src/main.yaml

@@ -34,6 +34,8 @@ components:
       $ref: "models.yaml#/joinRequest"
     projectDecision:
       $ref: "models.yaml#/projectDecision"
+    joinRequestDecision:
+      $ref: "models.yaml#/joinRequestDecision"
 
   securitySchemes:
       MyINPulse:
@@ -48,7 +50,7 @@ components:
 
 servers:
     - url: '{serverProtocol}://{serverHost}:{serverPort}'
-      description: API Server Environment
+      description: API Server
       variables:
         serverProtocol:
           enum: [http, https]
@@ -88,6 +90,10 @@ paths:
     $ref: "./adminApi.yaml#/paths/~1admin~1pending-accounts"
   /admin/accounts/validate/{userId}:
     $ref: "./adminApi.yaml#/paths/~1admin~1accounts~1validate~1{userId}"
+  /admin/request-join:
+    $ref: "./adminApi.yaml#/paths/~1admin~1request-join"
+  /admin/request-join/decision/{joinRequestId}:
+    $ref: "./adminApi.yaml#/paths/~1admin~1request-join~1decision~1{joinRequestId}"
   /admin/projects:
     $ref: "./adminApi.yaml#/paths/~1admin~1projects"
   /admin/projects/pending:

documentation/openapi/src/models.yaml

@@ -91,7 +91,7 @@ sectionCell:
       format: date # Using Java LocalDate -> YYYY-MM-DD
       description: The date when this cell was last modified.
       #readOnly: true # Typically updated by the server on modification
-      example: "2025-04-15"
+      example: "yyyy-MM-dd HH:mm"
 
 project:
   type: object
@@ -111,7 +111,7 @@ project:
       format: date # Using Java LocalDate -> YYYY-MM-DD
       description: The date when the project was created in the system.
       #readOnly: true # Set by server
-      example: "2024-11-20"
+      example: "yyyy-MM-dd HH:mm"
     logo:
       type: string
       format: byte
@@ -124,6 +124,18 @@ project:
         incoming to the server should be ignored as the client shouldn't be specifying them.
       example: "NaN"
 
+joinRequest:
+  type: object
+  description: Represents a request from an entrepreneur to join an already existing project.
+  properties:
+    idProject:
+      type: integer
+      description: the ID of the project the entrepreneur wants to join.
+      example: 42
+    entrepreneur:
+      $ref: "#/user-entrepreneur"
+      
+
 report:
   type: object
   description: Represents a report associated with an appointment.
@@ -171,17 +183,6 @@ appointment: # Corrected typo
       example: "Q3 Roadmap Planning"
     # Consider adding project ID or user IDs if relevant association exists
 
-joinRequest:
-  type: object
-  description: Represents a request from an entrepreneur to join an existing project.
-  properties:
-    projectId:
-      type: integer
-      description: The ID of the project the entrepreneur wants to join.
-      example: 12
-    # Consider adding userId if the requester isn't implicit from auth context
-    # Consider adding a message field
-
 projectDecision:
   type: object
   description: Represents a decision from an admin to accept a pending project.
@@ -198,3 +199,12 @@ projectDecision:
       type: boolean
       description: The boolean value of the decision.
       example: "true"
+
+joinRequestDecision:
+  type: object
+  description: Represents a decision from an admin to accept a pending project join request.
+  properties:
+    isAccepted:
+      type: boolean
+      description: The boolean value of the decision.
+      example: "true"

documentation/openapi/src/sharedApi.yaml

@@ -46,7 +46,7 @@ paths:
           name: date
           required: true
           schema: { type: string, format: date } # Expect YYYY-MM-DD
-          description: The modification date to filter by (YYYY-MM-DD).
+          description: The modification date to filter by (YYYY-MM-DD HH:mm).
       responses:
         "200":
           description: OK - List of section cells matching the criteria.
@@ -95,8 +95,8 @@ paths:
 
   /shared/projects/admin/{projectId}: # Path updated
     get:
-      operationId: getProjectAdmins
+      operationId: getProjectAdmin
-      summary: Get admins associated with a project
+      summary: Get admin associated with a project
       tags:
         - Shared API
       security:
@@ -110,7 +110,7 @@ paths:
           description: ID of the project.
       responses:
         "200":
-          description: OK - List of admins.
+          description: OK - admin.
           content:
             application/json:
               schema:
@@ -168,11 +168,13 @@ paths:
           description: ID of the appointment.
       responses:
         "200":
-          description: OK - Report content returned.
+          description: OK - Report PDF returned.
           content:
-            application/json:
+            application/pdf:
               schema:
-                  $ref: "./main.yaml#/components/schemas/report"
+                schema:
+                type: string
+                format: binary
         "401":
           description: Unauthorized.