From dfea20b9c44876cf36fb515afc923bf7cf221ae2 Mon Sep 17 00:00:00 2001 From: MAILLAL Anas Date: Wed, 16 Apr 2025 12:30:21 +0200 Subject: [PATCH] fix: aadded changes, doc is ssomewhat coherent still need to change some endpoint names in controller and some minor changes --- documentation/openapi/src/adminApi.yaml | 37 +---- documentation/openapi/src/bundled.yaml | 152 +++++------------- .../openapi/src/entrepreneurApi.yaml | 33 ---- documentation/openapi/src/main.yaml | 42 ++--- documentation/openapi/src/models.yaml | 19 ++- documentation/openapi/src/sharedApi.yaml | 6 +- documentation/openapi/src/unauthApi.yaml | 50 ++++-- 7 files changed, 109 insertions(+), 230 deletions(-) diff --git a/documentation/openapi/src/adminApi.yaml b/documentation/openapi/src/adminApi.yaml index 17f42e2..8c113e5 100644 --- a/documentation/openapi/src/adminApi.yaml +++ b/documentation/openapi/src/adminApi.yaml @@ -18,17 +18,6 @@ paths: type: array items: $ref: "./main.yaml#/components/schemas/project" - examples: - projectList: - value: - - idProject: 12 - projectName: "MyInpulse Mobile App" - creationDate: "2024-11-20" - logo: "base64..." - - idProject: 15 - projectName: "Data Analytics Dashboard" - creationDate: "2025-01-10" - logo: "base64..." "400": description: Bad Request - Invalid project data provided (e.g., missing required fields). "401": @@ -49,11 +38,6 @@ paths: application/json: schema: $ref: "./main.yaml#/components/schemas/project" - examples: - newProjectData: - value: - projectName: "New Initiative" - logo: "base64encodedstring..." responses: "201": # Use 201 Created for successful creation description: Created - Project added successfully. Returns the created project. @@ -114,17 +98,7 @@ paths: content: application/json: schema: - type: object - properties: - decision: - type: boolean - description: true to approve the project, false to reject it. - required: [decision] - example: - approve: - value: { "decision": true } - reject: - value: { "decision": false } + $ref: './main.yaml#/components/schemas/projectDecision' responses: "204": # Use 204 No Content for successful action with no body description: No Content - Decision processed successfully. @@ -182,7 +156,7 @@ paths: description: Unauthorized. /admin/appointments/report/{appointmentId}: - post: # Changed to POST for creation + post: operationId: createAppointmentReport summary: Create a report for an appointment description: Creates and links a new report (e.g., meeting minutes) to the specified appointment using the provided content. @@ -205,9 +179,6 @@ paths: application/json: schema: $ref: "./main.yaml#/components/schemas/report" - example: - value: - reportContent: "Discussed milestones. Action items assigned." responses: "201": description: Created - Report created and linked successfully. Returns the created report. @@ -242,10 +213,6 @@ paths: application/json: schema: $ref: "./main.yaml#/components/schemas/report" - example: - value: - idReport: 987 # Optional, should match existing if known - reportContent: "Updated discussion points. Final decisions made." responses: "200": description: OK - Report updated successfully. Returns the updated report. diff --git a/documentation/openapi/src/bundled.yaml b/documentation/openapi/src/bundled.yaml index f5747f2..1717edf 100644 --- a/documentation/openapi/src/bundled.yaml +++ b/documentation/openapi/src/bundled.yaml @@ -10,7 +10,7 @@ tags: description: API endpoints restricted to Admin users for management tasks. - name: Shared API description: API endpoints accessible by both Entrepreneurs and Admins. - - name: Account Management API + - name: Unauth API description: API endpoints related to user account management. components: schemas: @@ -182,32 +182,22 @@ components: type: integer description: The ID of the project the entrepreneur wants to join. example: 12 - ApiError: + projectDecision: type: object + description: Represents a decision from an admin to accept a pending project. properties: - timestamp: - type: string - format: date-time - description: Timestamp when the error occurred. - status: + projectId: type: integer - description: HTTP status code. - error: - type: string - description: 'High-level error description (e.g., Bad Request, Not Found).' - message: - type: string - description: A human-readable description of the error specific to this occurrence. - example: Required field 'projectName' is missing. - path: - type: string - description: The path of the request that triggered the error. - required: - - timestamp - - status - - error - - message - - path + description: The ID of the project the entrepreneur wants to join. + example: 12 + adminId: + 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' securitySchemes: MyINPulse: type: oauth2 @@ -240,9 +230,8 @@ servers: default: MyInpulseRealm description: Keycloak realm name. paths: - /accounts/finalize: + /unauth/finalize: post: - operationId: finalizeAccountSetup summary: Finalize account setup using authentication token description: |- Completes the user account creation/setup process in the MyInpulse system. @@ -250,21 +239,35 @@ paths: User details (name, email, etc.) are extracted from the authenticated user's token (e.g., Keycloak JWT). No request body is needed. The account is marked as pending admin validation upon successful finalization. tags: - - Account Management API - security: - - MyINPulse: - - MyINPulse-entrepreneur + - Unauth API responses: '201': description: Created - Account finalized and pending admin validation. Returns the user profile. - content: - application/json: - schema: - $ref: '#/components/schemas/user-entrepreneur' '400': description: Bad Request - Problem processing the token or user data derived from it. '401': description: Unauthorized - Valid authentication token required. + '/unauth/request-join/{projectId}': + post: + summary: Request to join an existing project + description: Submits a request for the authenticated user (keycloack authenticated) to join the project specified by projectId. Their role is then changed to entrepreneur in server and Keycloak. This requires approval from a project admin. + tags: + - Unauth API + parameters: + - in: path + name: projectId + required: true + schema: + type: integer + description: The ID of the project to request joining. + example: 15 + responses: + '202': + description: Accepted - Join request submitted and pending approval. + '400': + description: Bad Request - Invalid project ID format or already member/request pending. + '401': + description: Unauthorized. /admin/pending-accounts: get: operationId: getPendingAccounts @@ -330,17 +333,6 @@ paths: type: array items: $ref: '#/components/schemas/project' - examples: - projectList: - value: - - idProject: 12 - projectName: MyInpulse Mobile App - creationDate: '2024-11-20' - logo: base64... - - idProject: 15 - projectName: Data Analytics Dashboard - creationDate: '2025-01-10' - logo: base64... '400': description: 'Bad Request - Invalid project data provided (e.g., missing required fields).' '401': @@ -361,11 +353,6 @@ paths: application/json: schema: $ref: '#/components/schemas/project' - examples: - newProjectData: - value: - projectName: New Initiative - logo: base64encodedstring... responses: '201': description: Created - Project added successfully. Returns the created project. @@ -425,20 +412,7 @@ paths: content: application/json: schema: - type: object - properties: - decision: - type: boolean - description: 'true to approve the project, false to reject it.' - required: - - decision - example: - approve: - value: - decision: true - reject: - value: - decision: false + $ref: '#/components/schemas/projectDecision' responses: '204': description: No Content - Decision processed successfully. @@ -471,9 +445,6 @@ paths: application/json: schema: $ref: '#/components/schemas/report' - example: - value: - reportContent: Discussed milestones. Action items assigned. responses: '201': description: Created - Report created and linked successfully. Returns the created report. @@ -509,10 +480,6 @@ paths: application/json: schema: $ref: '#/components/schemas/report' - example: - value: - idReport: 987 - reportContent: Updated discussion points. Final decisions made. responses: '200': description: OK - Report updated successfully. Returns the updated report. @@ -673,7 +640,7 @@ paths: description: Forbidden - User does not have access to this project. '404': description: Not Found - Project not found. - '/shared/projects/admins/{projectId}': + '/shared/projects/admin/{projectId}': get: operationId: getProjectAdmins summary: Get admins associated with a project @@ -697,9 +664,7 @@ paths: content: application/json: schema: - type: array - items: - $ref: '#/components/schemas/user-admin' + $ref: '#/components/schemas/user-admin' '401': description: Unauthorized. '403': @@ -798,31 +763,6 @@ paths: description: Bad Request - Invalid appointment details. '401': description: Unauthorized. - '/entrepreneur/projects/request-join/{projectId}': - post: - operationId: requestToJoinProject - summary: Request to join an existing project - description: Submits a request for the authenticated entrepreneur to join the project specified by projectId. This requires approval from a project admin. - tags: - - Entrepreneurs API - security: - - MyINPulse: - - MyINPulse-entrepreneur - parameters: - - in: path - name: projectId - required: true - schema: - type: integer - description: The ID of the project to request joining. - example: 15 - responses: - '202': - description: Accepted - Join request submitted and pending approval. - '400': - description: Bad Request - Invalid project ID format or already member/request pending. - '401': - description: Unauthorized. /entrepreneur/projects/request: post: operationId: requestProjectCreation @@ -850,18 +790,6 @@ paths: description: 'Bad Request - Invalid input (e.g., missing name).' '401': description: Unauthorized. - '403': - description: Forbidden - User does not have entrepreneur privileges. - content: - application/json: - schema: - $ref: '#/components/schemas/ApiError' - '500': - description: Internal Server Error. - content: - application/json: - schema: - $ref: '#/components/schemas/ApiError' /entrepreneur/sectionCells: post: operationId: addSectionCell diff --git a/documentation/openapi/src/entrepreneurApi.yaml b/documentation/openapi/src/entrepreneurApi.yaml index 6b14a1e..3c67c19 100644 --- a/documentation/openapi/src/entrepreneurApi.yaml +++ b/documentation/openapi/src/entrepreneurApi.yaml @@ -27,39 +27,6 @@ paths: description: Bad Request - Invalid input (e.g., missing name). "401": description: Unauthorized. - "403": - description: Forbidden - User does not have entrepreneur privileges. - content: - application/json: { schema: { $ref: "./main.yaml#/components/schemas/ApiError" } } - "500": - description: Internal Server Error. - content: - application/json: { schema: { $ref: "./main.yaml#/components/schemas/ApiError" } } - - /entrepreneur/projects/request-join/{projectId}: - post: - operationId: requestToJoinProject - summary: Request to join an existing project - description: Submits a request for the authenticated entrepreneur to join the project specified by projectId. This requires approval from a project admin. - tags: - - Entrepreneurs API - security: - - MyINPulse: [MyINPulse-entrepreneur] - parameters: - - in: path - name: projectId - required: true - schema: - type: integer - description: The ID of the project to request joining. - example: 15 - responses: # Moved responses block to correct level - "202": - description: Accepted - Join request submitted and pending approval. - "400": - description: Bad Request - Invalid project ID format or already member/request pending. - "401": - description: Unauthorized. /entrepreneur/sectionCells: # Base path post: diff --git a/documentation/openapi/src/main.yaml b/documentation/openapi/src/main.yaml index ceadc8e..6538d4e 100644 --- a/documentation/openapi/src/main.yaml +++ b/documentation/openapi/src/main.yaml @@ -11,7 +11,7 @@ tags: description: API endpoints restricted to Admin users for management tasks. - name: Shared API description: API endpoints accessible by both Entrepreneurs and Admins. - - name: Account Management API + - name: Unauth API description: API endpoints related to user account management. components: @@ -32,32 +32,8 @@ components: $ref: "models.yaml#/appointment" joinRequest: $ref: "models.yaml#/joinRequest" - ApiError: - type: object - properties: - timestamp: - type: string - format: date-time - description: Timestamp when the error occurred. - status: - type: integer - description: HTTP status code. - error: - type: string - description: High-level error description (e.g., Bad Request, Not Found). - message: - type: string - description: A human-readable description of the error specific to this occurrence. - example: Required field 'projectName' is missing. - path: - type: string - description: The path of the request that triggered the error. - required: - - timestamp - - status - - error - - message - - path + projectDecision: + $ref: "models.yaml#/projectDecision" securitySchemes: MyINPulse: @@ -97,8 +73,10 @@ paths: # \___/|_| |_|\__,_|\__,_|\__|_| |_/_/ \_\ .__/|_| # |_| - /accounts/finalize: - $ref: "./unauthApi.yaml#/paths/~1accounts~1finalize" + /unauth/finalize: + $ref: "./unauthApi.yaml#/paths/~1unauth~1finalize" + /unauth/request-join/{projectId}: + $ref: "./unauthApi.yaml#/paths/~1unauth~1request-join~1{projectId}" # _ ____ __ __ ___ _ _ _ ____ ___ # / \ | _ \| \/ |_ _| \ | | / \ | _ \_ _| @@ -135,8 +113,8 @@ paths: $ref: "./sharedApi.yaml#/paths/~1shared~1projects~1sectionCells~1{projectId}~1{sectionId}~1{date}" /shared/projects/entrepreneurs/{projectId}: $ref: "./sharedApi.yaml#/paths/~1shared~1projects~1entrepreneurs~1{projectId}" - /shared/projects/admins/{projectId}: - $ref: "./sharedApi.yaml#/paths/~1shared~1projects~1admins~1{projectId}" + /shared/projects/admin/{projectId}: + $ref: "./sharedApi.yaml#/paths/~1shared~1projects~1admin~1{projectId}" /shared/projects/appointments/{projectId}: $ref: "./sharedApi.yaml#/paths/~1shared~1projects~1appointments~1{projectId}" /shared/appointments/report/{appointmentId}: @@ -154,8 +132,6 @@ paths: # / ___ \| __/| | # /_/ \_\_| |___| # - /entrepreneur/projects/request-join/{projectId}: - $ref: "./entrepreneurApi.yaml#/paths/~1entrepreneur~1projects~1request-join~1{projectId}" /entrepreneur/projects/request: $ref: "./entrepreneurApi.yaml#/paths/~1entrepreneur~1projects~1request" /entrepreneur/sectionCells: diff --git a/documentation/openapi/src/models.yaml b/documentation/openapi/src/models.yaml index 1c165b4..8a8f578 100644 --- a/documentation/openapi/src/models.yaml +++ b/documentation/openapi/src/models.yaml @@ -180,4 +180,21 @@ joinRequest: 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 \ No newline at end of file + # Consider adding a message field + +projectDecision: + type: object + description: Represents a decision from an admin to accept a pending project. + properties: + projectId: + type: integer + description: The ID of the project the entrepreneur wants to join. + example: 12 + adminId: + 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" \ No newline at end of file diff --git a/documentation/openapi/src/sharedApi.yaml b/documentation/openapi/src/sharedApi.yaml index d600cf7..f142890 100644 --- a/documentation/openapi/src/sharedApi.yaml +++ b/documentation/openapi/src/sharedApi.yaml @@ -93,7 +93,7 @@ paths: "404": description: Not Found - Project not found. - /shared/projects/admins/{projectId}: # Path updated + /shared/projects/admin/{projectId}: # Path updated get: operationId: getProjectAdmins summary: Get admins associated with a project @@ -114,9 +114,7 @@ paths: content: application/json: schema: - type: array - items: - $ref: "./main.yaml#/components/schemas/user-admin" + $ref: "./main.yaml#/components/schemas/user-admin" "401": description: Unauthorized. "403": diff --git a/documentation/openapi/src/unauthApi.yaml b/documentation/openapi/src/unauthApi.yaml index c9676f6..6368e13 100644 --- a/documentation/openapi/src/unauthApi.yaml +++ b/documentation/openapi/src/unauthApi.yaml @@ -7,9 +7,8 @@ # |_| paths: - /accounts/finalize: # Path renamed from /unauth/create_account + /unauth/finalize: post: - operationId: finalizeAccountSetup # Renamed operationId summary: Finalize account setup using authentication token description: |- Completes the user account creation/setup process in the MyInpulse system. @@ -17,18 +16,45 @@ paths: User details (name, email, etc.) are extracted from the authenticated user's token (e.g., Keycloak JWT). No request body is needed. The account is marked as pending admin validation upon successful finalization. tags: - - Account Management API # Changed tag - security: - - MyINPulse: [MyINPulse-entrepreneur] # Security requirement remains as per clarification - # No requestBody needed as per clarification + - Unauth API responses: - "201": # Use 201 Created or 200 OK if it returns the user profile + "201": description: Created - Account finalized and pending admin validation. Returns the user profile. - content: - application/json: - schema: - $ref: './main.yaml#/components/schemas/user-entrepreneur' # Return the created user profile "400": description: Bad Request - Problem processing the token or user data derived from it. "401": - description: Unauthorized - Valid authentication token required. \ No newline at end of file + description: Unauthorized - Valid authentication token required. + /unauth/request-join/{projectId}: + post: + summary: Request to join an existing project + description: Submits a request for the authenticated user (keycloack authenticated) to join the project specified by projectId. Their role is then changed to entrepreneur in server and Keycloak. This requires approval from a project admin. + tags: + - Unauth API + parameters: + - in: path + name: projectId + required: true + schema: + type: integer + description: The ID of the project to request joining. + example: 15 + responses: # Moved responses block to correct level + "202": + description: Accepted - Join request submitted and pending approval. + "400": + description: Bad Request - Invalid project ID format or already member/request pending. + "401": + description: Unauthorized. + /unauth/request-admin-role: + post: + summary: Request to join an existing project + description: Submits a request for the authenticated user (keycloack authenticated) to become an admin. Their role is then changed to admin in server and Keycloak. This requires approval from a project admin. + tags: + - Unauth API + responses: + "202": + description: Accepted - Become admin request submitted and pending approval. + "400": + description: Bad Request - Invalid project ID format or already member/request pending. + "401": + description: Unauthorized. \ No newline at end of file