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

2025-04-21 10:54:50 +02:00 · 2025-04-21 10:54:50 +02:00 · 832539f43b
commit 832539f43b
parent dfea20b9c4
6 changed files with 179 additions and 47 deletions
--- a/documentation/openapi/src/adminApi.yaml
+++ b/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 rejected (decision=false), the pending project data might be archived or deleted based on business logic.
+        If approved (isAccepted=true), the project status changes, and it's linked to the involved users.
+        If rejected (isAccepted=false), the pending project data might be archived or deleted based on business logic.
      security:
          - MyINPulse: [MyINPulse-admin]
      parameters:
--- a/documentation/openapi/src/bundled.yaml
+++ b/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.
-          example: 12
+          description: the ID of the project the entrepreneur wants to join.
+          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 rejected (decision=false), the pending project data might be archived or deleted based on business logic.
+        If approved (isAccepted=true), the project status changes, and it's linked to the involved users.
+        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
-      summary: Get admins associated with a project
+      operationId: getProjectAdmin
+      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:
--- a/documentation/openapi/src/entrepreneurApi.yaml
+++ b/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:
--- a/documentation/openapi/src/main.yaml
+++ b/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:
--- a/documentation/openapi/src/models.yaml
+++ b/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.
@ -194,6 +195,15 @@ projectDecision:
      type: integer
      description: The ID of the project the admin who will supervise the project in case of admission.
      example: 2
+    isAccepted:
+      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.
--- a/documentation/openapi/src/sharedApi.yaml
+++ b/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
-      summary: Get admins associated with a project
+      operationId: getProjectAdmin
+      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.