diff --git a/documentation/openapi/src/adminApi.yaml b/documentation/openapi/src/adminApi.yaml index d5e1a08..17f42e2 100644 --- a/documentation/openapi/src/adminApi.yaml +++ b/documentation/openapi/src/adminApi.yaml @@ -1,214 +1,311 @@ -# _ ____ __ __ ___ _ _ _ ____ ___ -# / \ | _ \| \/ |_ _| \ | | / \ | _ \_ _| -# / _ \ | | | | |\/| || || \| | / _ \ | |_) | | -# / ___ \| |_| | | | || || |\ | / ___ \| __/| | -# /_/ \_\____/|_| |_|___|_| \_| /_/ \_\_| |___| -# +# Admin API Endpoints paths: /admin/projects: get: - summary: Retourne la liste of projets associés à l'admin - tags: - - Admin API + operationId: getAdminProjects + summary: Get projects associated with the admin + tags: + - Admin API security: - - MyINPulse: - - MyINPulse-admin - description: - JSON array of who's elements are objects containing necessary information for the view - (project name, entrepreneur names, etc..) - of the projects an admin is watching over. + - MyINPulse: [MyINPulse-admin] + description: Retrieves a list of projects managed by the requesting admin, including key details for overview. responses: "200": - description: OK + description: OK - List of projects returned successfully. content: application/json: schema: type: array items: - $ref: "main.yaml#/components/schemas/project" + $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 + description: Bad Request - Invalid project data provided (e.g., missing required fields). "401": - description: Authorization information is missing or invalid - /admin/projects/pending/decision: + description: Unauthorized - Authentication required or invalid token. + post: - summary: valider un projet en attente de validation + operationId: addProjectManually + summary: Manually add a new project + description: Creates a new project with the provided details. tags: - Admin API - description: - if the request is accepted the status of the - project is changed to ongoing, entrepreneur - account is confirmed and the project is linked - to the admin accepting the request and the - entrepreneur requesting it. Else the pending - project and user info are deleted. security: - - MyINPulse: - - MyINPulse-admin + - MyINPulse: [MyINPulse-admin] requestBody: required: true + description: Project details to create. `idProject` and `creationDate` will be ignored if sent and set by the server. + content: + 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. + content: + application/json: + schema: + $ref: "./main.yaml#/components/schemas/project" + "400": + description: Bad Request - Invalid project data provided (e.g., missing required fields). + "401": + description: Unauthorized. + + + /admin/projects/pending: + get: + operationId: getPendingProjects + summary: Get projects awaiting validation + tags: + - Admin API + security: + - MyINPulse: [MyINPulse-admin] + description: Retrieves a list of projects submitted by entrepreneurs that are pending admin approval. + responses: + "200": + description: OK - List of pending projects returned. + content: + application/json: + schema: + type: array + items: + $ref: "./main.yaml#/components/schemas/project" # Assuming pending projects use the same schema + "401": + description: Unauthorized. + + /admin/projects/pending/decision/{pendingProjectId}: + post: + operationId: decidePendingProject + summary: Approve or reject a pending project + tags: + - 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. + security: + - MyINPulse: [MyINPulse-admin] + parameters: + - in: path + name: pendingProjectId # Corrected typo and name change + required: true + schema: + type: integer + description: The ID of the pending project to decide upon. + example: 7 + requestBody: + required: true + description: Decision payload. content: application/json: schema: type: object properties: - pedingProjectId: - type: integer decision: type: boolean - + description: true to approve the project, false to reject it. + required: [decision] + example: + approve: + value: { "decision": true } + reject: + value: { "decision": false } responses: - "200": - description: OK + "204": # Use 204 No Content for successful action with no body + description: No Content - Decision processed successfully. "400": - description: Bad request + description: Bad Request - Invalid input (e.g., missing decision). "401": - description: Authorization information is - missing or invalid - - /admin/projects/add: - post: - summary: Ajout manuel d'un projet - description: - Adds a project with the - inputed details + description: Unauthorized. + + + /admin/pending-accounts: # Path updated + get: + operationId: getPendingAccounts + summary: Get accounts awaiting validation + description: Retrieves a list of entrepreneur user accounts that are pending admin validation. tags: - Admin API security: - - MyINPulse: - - MyINPulse-admin - requestBody: - required: true - content: - application/json: - schema: - $ref: "main.yaml#/components/schemas/project" - + - MyINPulse: [MyINPulse-admin] responses: - "200": - description: OK - "400": - description: Bad request + "200": + description: OK - List of pending accounts returned. + content: + application/json: + schema: + type: array + items: + $ref: "./main.yaml#/components/schemas/user-entrepreneur" "401": - description: Authorization information is - missing or invalid + description: Unauthorized. + + /admin/accounts/validate/{userId}: + post: # Changed to POST as it changes state + operationId: validateUserAccount + summary: Validate a pending user account + description: Marks the user account specified by userId as validated/active. + tags: + - Admin API + security: + - MyINPulse: [MyINPulse-admin] + parameters: + - in: path + name: userId + required: true + schema: + type: integer + description: The ID of the user account to validate. + example: 102 + responses: + "204": + description: No Content - Account validated successfully. + "400": + description: Bad Request - Invalid user ID format. + + "401": + description: Unauthorized. /admin/appointments/report/{appointmentId}: - put: - summary: enregistrer un rapport du rendez-vous - description: - Generate a PDF file formatted - from input text and links it - to the appointement. + post: # Changed to POST for creation + 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. tags: - Admin API security: - - MyINPulse: - - MyINPulse-admin + - MyINPulse: [MyINPulse-admin] parameters: - in: path name: appointmentId required: true schema: type: integer + description: ID of the appointment to add a report to. + example: 303 requestBody: required: true + description: Report content. `idReport` will be ignored if sent. content: application/json: schema: - $ref: "main.yaml#/components/schemas/report" - + $ref: "./main.yaml#/components/schemas/report" + example: + value: + reportContent: "Discussed milestones. Action items assigned." responses: - "200": - description: OK + "201": + description: Created - Report created and linked successfully. Returns the created report. + content: + application/json: + schema: { $ref: "./main.yaml#/components/schemas/report" } "400": - description: Bad request + description: Bad Request - Invalid input (e.g., missing content, invalid appointment ID format). "401": - description: Authorization information is - missing or invalid - post: - summary: modifier un rapport déja éxistant du rendez-vous - description: - Modifies the report file to input - text and links it to the appointement. + description: Unauthorized. + + put: # Changed to PUT for update/replacement + operationId: updateAppointmentReport + summary: Update an existing appointment report + description: Updates the content of an existing report linked to the specified appointment. Replaces the entire report content. tags: - Admin API security: - - MyINPulse: - - MyINPulse-admin + - MyINPulse: [MyINPulse-admin] parameters: - in: path name: appointmentId required: true schema: type: integer + description: ID of the appointment whose report needs updating. + example: 303 requestBody: required: true + description: New report content. `idReport` in the body should match the existing report's ID or will be ignored. content: application/json: schema: - $ref: "main.yaml#/components/schemas/report" - + $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 + "200": + description: OK - Report updated successfully. Returns the updated report. + content: + application/json: + schema: { $ref: "./main.yaml#/components/schemas/report" } "400": - description: Bad request + description: Bad Request - Invalid input (e.g., missing content). "401": - description: Authorization information is - missing or invalid + description: Unauthorized. - /admin/projects/remove/{projectId}: + /admin/projects/{projectId}: delete: - summary: supression d'un project - description: - Removes the project - with the inputed id projectId + operationId: removeProject + summary: Remove a project + description: Permanently removes the project specified by projectId and potentially related data (use with caution). tags: - Admin API security: - - MyINPulse: - - MyINPulse-admin + - MyINPulse: [MyINPulse-admin] parameters: - in: path name: projectId required: true schema: type: integer - + description: The ID of the project to remove. + example: 12 responses: - "200": - description: OK + "204": + description: No Content - Project removed successfully. "400": - description: Bad request + description: Bad Request - Invalid project ID format. "401": - description: Authorization information is - missing or invalid - + description: Unauthorized. + - /admin/projects/pending: - get: - summary: Retourne la liste des projets en attente de validation - tags: + + /admin/make-admin/{userId}: + post: + operationId: grantAdminRights + summary: Grant admin rights to a user + tags: - Admin API security: - - MyINPulse: - - MyINPulse-admin - description: - JSON array of who's elements are objects containing - necessary information for the view (project name, etc..) - of all pending projects. + - MyINPulse: [MyINPulse-admin] + description: Elevates the specified user to also have administrator privileges. Assumes the user already exists. + parameters: + - in: path + name: userId + required: true + schema: + type: integer + description: The ID of the user to grant admin rights. + example: 103 responses: - "200": - description: OK - content: - application/json: - schema: - type: array - items: - $ref: "main.yaml#/components/schemas/project" + "204": # Use 204 No Content + description: No Content - Admin rights granted successfully. "400": - description: Bad request + description: Bad Request - Invalid user ID format or user is already an admin. "401": - description: Authorization information is missing or invalid \ No newline at end of file + description: Unauthorized. \ No newline at end of file diff --git a/documentation/openapi/src/bundled.yaml b/documentation/openapi/src/bundled.yaml index 66ded43..f5747f2 100644 --- a/documentation/openapi/src/bundled.yaml +++ b/documentation/openapi/src/bundled.yaml @@ -1,15 +1,17 @@ openapi: 3.0.3 info: - title: MyInpulse Backend Api - description: this document servers as a documentation for the backend api. - version: 0.2.0 + title: MyInpulse Backend API + description: 'This serves as an OpenAPI documentation for the MyInpulse backend service, covering operations for Entrepreneurs, Admins, and shared functionalities.' + version: 0.2.1 tags: - name: Entrepreneurs API - description: La partie de l'api dédiée aux entrepreneurs + description: API endpoints primarily for Entrepreneur users. - name: Admin API - description: La partie de l'api dédiée aux entrepreneurs + description: API endpoints restricted to Admin users for management tasks. - name: Shared API - description: La partie de l'api dédiée aux entrepreneurs et admins + description: API endpoints accessible by both Entrepreneurs and Admins. + - name: Account Management API + description: API endpoints related to user account management. components: schemas: user: @@ -17,19 +19,30 @@ components: properties: idUser: type: integer + description: Unique identifier for the user. + example: 101 userSurname: type: string + description: User's surname (last name). + example: Doe userName: type: string + description: User's given name (first name). + example: John primaryMail: type: string - example: example@exmaple.com + format: email + description: User's primary email address. + example: john.doe@example.com secondaryMail: type: string - example: example@exmaple.com + format: email + description: User's secondary email address (optional). + example: j.doe@personal.com phoneNumber: type: string - example: 0612345678 + description: User's phone number. + example: '+33612345678' user-entrepreneur: allOf: - $ref: '#/components/schemas/user' @@ -37,180 +50,407 @@ components: properties: school: type: string - example: enseirb + description: The school the entrepreneur attends/attended. + example: ENSEIRB-MATMECA course: type: string - example: info + description: The specific course or program of study. + example: Electronics sneeStatus: type: boolean - example: false + description: Indicates if the user has SNEE status (Statut National d'Étudiant-Entrepreneur). + example: true + example: + idUser: 101 + userSurname: Doe + userName: John + primaryMail: john.doe@example.com + secondaryMail: j.doe@personal.com + phoneNumber: '+33612345678' + school: ENSEIRB-MATMECA + course: Electronics + sneeStatus: true user-admin: allOf: - $ref: '#/components/schemas/user' + example: + idUser: 55 + userSurname: Admin + userName: Super + primaryMail: admin@myinpulse.com + phoneNumber: '+33512345678' sectionCell: type: object + description: Represents a cell (like a sticky note) within a specific section of a project's Lean Canvas. properties: idSectionCell: type: integer - example: this the cell (postit id) + description: Unique identifier for the section cell. + example: 508 sectionId: type: integer + description: 'Identifier of the Lean Canvas section this cell belongs to (e.g., 1 for Problem, 2 for Solution).' + example: 1 contentSectionCell: type: string + description: The text content of the section cell. + example: Users find it hard to track project progress. modificationDate: type: string - example: 02-05-2025 + format: date + description: The date when this cell was last modified. + example: '2025-04-15' project: type: object + description: Represents a project being managed or developed. properties: idProject: type: integer + description: Unique identifier for the project. + example: 12 projectName: type: string + description: The name of the project. + example: MyInpulse Mobile App creationDate: type: string - example: 02-05-2025 + format: date + description: The date when the project was created in the system. + example: '2024-11-20' logo: - example: to be discussed not yet fixed type: string - format: binary + format: byte + description: Base64 encoded string representing the project logo image. + example: /*Base64 encoded string representing the project logo image*/ + status: + type: string + enum: + - PENDING + - ACTIVE + - ENDED + - ABORTED + - REJECTED + description: 'Corresponds to a status enum internal to the backend, it''s value in in requests incoming to the server should be ignored as the client shouldn''t be specifying them.' + example: NaN report: type: object + description: Represents a report associated with an appointment. properties: idReport: type: integer + description: Unique identifier for the report. + example: 987 reportContent: type: string - appointement: + description: The textual content of the report. Could be plain text or Markdown (specify if known). + example: Discussed roadmap milestones for Q3. Agreed on preliminary UI mockups. + appointment: type: object + description: Represents a scheduled meeting or appointment. properties: + idAppointment: + type: integer + description: Unique identifier for the appointment. + example: 303 appointmentDate: type: string - example: 02-05-2025 + format: date + description: The date of the appointment. + example: '2025-05-10' appointmentTime: type: string - example: '10:15:30' + format: time + description: The time of the appointment (local time). + example: '14:30:00' appointmentDuration: type: string + description: 'Duration of the appointment in ISO 8601 duration format (e.g., PT1H30M for 1 hour 30 minutes).' + example: PT1H appointmentPlace: type: string + description: Location or meeting link for the appointment. + example: 'Meeting Room 3 / https://meet.example.com/abc-def-ghi' appointmentSubject: type: string + description: The main topic or subject of the appointment. + example: Q3 Roadmap Planning + 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 + 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 securitySchemes: MyINPulse: type: oauth2 + description: OAuth2 authentication using Keycloak. flows: implicit: - authorizationUrl: 'http://localhost:7080' + authorizationUrl: '{keycloakBaseUrl}/realms/{keycloakRealm}/protocol/openid-connect/auth' scopes: - MyINPulse-admin: Administrateur - MyINPulse-entrepreneur: Utilisateur + MyINPulse-admin: Grants administrator access. + MyINPulse-entrepreneur: Grants standard entrepreneur user access. servers: - - url: 'http://localhost:8081/' - description: Backend server + - url: '{serverProtocol}://{serverHost}:{serverPort}' + description: API Server Environment + variables: + serverProtocol: + enum: + - http + - https + default: http + serverHost: + default: localhost + serverPort: + enum: + - '8081' + default: '8081' + keycloakBaseUrl: + default: 'http://localhost:7080' + description: Base URL for the Keycloak server. + keycloakRealm: + default: MyInpulseRealm + description: Keycloak realm name. paths: - /admin/projects: + /accounts/finalize: + post: + operationId: finalizeAccountSetup + summary: Finalize account setup using authentication token + description: |- + Completes the user account creation/setup process in the MyInpulse system. + This endpoint requires the user to be authenticated via Keycloak (e.g., after initial login). + 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 + 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. + /admin/pending-accounts: get: - summary: Retourne la liste of projets associés à l'admin + operationId: getPendingAccounts + summary: Get accounts awaiting validation + description: Retrieves a list of entrepreneur user accounts that are pending admin validation. tags: - Admin API security: - MyINPulse: - MyINPulse-admin - description: 'JSON array of who''s elements are objects containing necessary information for the view (project name, entrepreneur names, etc..) of the projects an admin is watching over.' responses: '200': - description: OK + description: OK - List of pending accounts returned. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/user-entrepreneur' + '401': + description: Unauthorized. + '/admin/accounts/validate/{userId}': + post: + operationId: validateUserAccount + summary: Validate a pending user account + description: Marks the user account specified by userId as validated/active. + tags: + - Admin API + security: + - MyINPulse: + - MyINPulse-admin + parameters: + - in: path + name: userId + required: true + schema: + type: integer + description: The ID of the user account to validate. + example: 102 + responses: + '204': + description: No Content - Account validated successfully. + '400': + description: Bad Request - Invalid user ID format. + '401': + description: Unauthorized. + /admin/projects: + get: + operationId: getAdminProjects + summary: Get projects associated with the admin + tags: + - Admin API + security: + - MyINPulse: + - MyINPulse-admin + description: 'Retrieves a list of projects managed by the requesting admin, including key details for overview.' + responses: + '200': + description: OK - List of projects returned successfully. content: application/json: schema: 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 + description: 'Bad Request - Invalid project data provided (e.g., missing required fields).' '401': - description: Authorization information is missing or invalid - /admin/projects/pending/decision: + description: Unauthorized - Authentication required or invalid token. post: - summary: valider un projet en attente de validation + operationId: addProjectManually + summary: Manually add a new project + description: Creates a new project with the provided details. tags: - Admin API - description: 'if the request is accepted the status of the project is changed to ongoing, entrepreneur account is confirmed and the project is linked to the admin accepting the request and the entrepreneur requesting it. Else the pending project and user info are deleted.' security: - MyINPulse: - MyINPulse-admin requestBody: required: true + description: Project details to create. `idProject` and `creationDate` will be ignored if sent and set by the server. + content: + 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. + content: + application/json: + schema: + $ref: '#/components/schemas/project' + '400': + description: 'Bad Request - Invalid project data provided (e.g., missing required fields).' + '401': + description: Unauthorized. + /admin/projects/pending: + get: + operationId: getPendingProjects + summary: Get projects awaiting validation + tags: + - Admin API + security: + - MyINPulse: + - MyINPulse-admin + description: Retrieves a list of projects submitted by entrepreneurs that are pending admin approval. + responses: + '200': + description: OK - List of pending projects returned. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/project' + '401': + description: Unauthorized. + '/admin/projects/pending/decision/{pendingProjectId}': + post: + operationId: decidePendingProject + summary: Approve or reject a pending project + tags: + - 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. + security: + - MyINPulse: + - MyINPulse-admin + parameters: + - in: path + name: pendingProjectId + required: true + schema: + type: integer + description: The ID of the pending project to decide upon. + example: 7 + requestBody: + required: true + description: Decision payload. content: application/json: schema: type: object properties: - pedingProjectId: - type: integer decision: type: boolean + description: 'true to approve the project, false to reject it.' + required: + - decision + example: + approve: + value: + decision: true + reject: + value: + decision: false responses: - '200': - description: OK + '204': + description: No Content - Decision processed successfully. '400': - description: Bad request + description: 'Bad Request - Invalid input (e.g., missing decision).' '401': - description: Authorization information is missing or invalid - /admin/projects/add: - post: - summary: Ajout manuel d'un projet - description: Adds a project with the inputed details - tags: - - Admin API - security: - - MyINPulse: - - MyINPulse-admin - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/project' - responses: - '200': - description: OK - '400': - description: Bad request - '401': - description: Authorization information is missing or invalid + description: Unauthorized. '/admin/appointments/report/{appointmentId}': - put: - summary: enregistrer un rapport du rendez-vous - description: Generate a PDF file formatted from input text and links it to the appointement. - tags: - - Admin API - security: - - MyINPulse: - - MyINPulse-admin - parameters: - - in: path - name: appointmentId - required: true - schema: - type: integer - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/report' - responses: - '200': - description: OK - '400': - description: Bad request - '401': - description: Authorization information is missing or invalid post: - summary: modifier un rapport déja éxistant du rendez-vous - description: Modifies the report file to input text and links it to the appointement. + 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.' tags: - Admin API security: @@ -222,23 +462,73 @@ paths: required: true schema: type: integer + description: ID of the appointment to add a report to. + example: 303 requestBody: required: true + description: Report content. `idReport` will be ignored if sent. content: 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. + content: + application/json: + schema: + $ref: '#/components/schemas/report' + '400': + description: 'Bad Request - Invalid input (e.g., missing content, invalid appointment ID format).' + '401': + description: Unauthorized. + put: + operationId: updateAppointmentReport + summary: Update an existing appointment report + description: Updates the content of an existing report linked to the specified appointment. Replaces the entire report content. + tags: + - Admin API + security: + - MyINPulse: + - MyINPulse-admin + parameters: + - in: path + name: appointmentId + required: true + schema: + type: integer + description: ID of the appointment whose report needs updating. + example: 303 + requestBody: + required: true + description: New report content. `idReport` in the body should match the existing report's ID or will be ignored. + content: + application/json: + schema: + $ref: '#/components/schemas/report' + example: + value: + idReport: 987 + reportContent: Updated discussion points. Final decisions made. responses: '200': - description: OK + description: OK - Report updated successfully. Returns the updated report. + content: + application/json: + schema: + $ref: '#/components/schemas/report' '400': - description: Bad request + description: 'Bad Request - Invalid input (e.g., missing content).' '401': - description: Authorization information is missing or invalid - '/admin/projects/remove/{projectId}': + description: Unauthorized. + '/admin/projects/{projectId}': delete: - summary: supression d'un project - description: Removes the project with the inputed id projectId + operationId: removeProject + summary: Remove a project + description: Permanently removes the project specified by projectId and potentially related data (use with caution). tags: - Admin API security: @@ -250,99 +540,96 @@ paths: required: true schema: type: integer + description: The ID of the project to remove. + example: 12 responses: - '200': - description: OK + '204': + description: No Content - Project removed successfully. '400': - description: Bad request + description: Bad Request - Invalid project ID format. '401': - description: Authorization information is missing or invalid - /admin/projects/pending: - get: - summary: Retourne la liste des projets en attente de validation + description: Unauthorized. + '/admin/make-admin/{userId}': + post: + operationId: grantAdminRights + summary: Grant admin rights to a user tags: - Admin API security: - MyINPulse: - MyINPulse-admin - description: 'JSON array of who''s elements are objects containing necessary information for the view (project name, etc..) of all pending projects.' + description: Elevates the specified user to also have administrator privileges. Assumes the user already exists. + parameters: + - in: path + name: userId + required: true + schema: + type: integer + description: The ID of the user to grant admin rights. + example: 103 responses: - '200': - description: OK - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/project' + '204': + description: No Content - Admin rights granted successfully. '400': - description: Bad request + description: Bad Request - Invalid user ID format or user is already an admin. '401': - description: Authorization information is missing or invalid + description: Unauthorized. /shared/appointments/upcoming: get: - summary: Retourne la list des prochains rendez-vous de l'utilisateur + operationId: getUpcomingAppointments + summary: Get upcoming appointments for the user tags: - Shared API security: - MyINPulse: - - MyINPulse-admin - MyINPulse-entrepreneur - description: 'JSON array of upcoming appointment data (name, date, time etc..) for a user.' + - MyINPulse-admin + description: Retrieves a list of appointments scheduled for the authenticated user (either entrepreneur or admin) in the future. responses: '200': - description: OK + description: OK - List of upcoming appointments. content: application/json: schema: type: array items: - $ref: '#/components/schemas/appointement' - '400': - description: Bad request + $ref: '#/components/schemas/appointment' '401': - description: Authorization information is missing or invalid - '/shared/projects/sectionCell/{projectId}/{sectionId}/{date}': + description: Unauthorized. + '/shared/projects/sectionCells/{projectId}/{sectionId}/{date}': get: - summary: Retourne la liste de sections de LC avec un titre donné + operationId: getSectionCellsByDate + summary: Get project section cells modified on a specific date tags: - Shared API security: - MyINPulse: - - MyINPulse-admin - MyINPulse-entrepreneur - description: JSON array containing Lean Canvas section data with a title for the current date (or given date if the date parameter is passed) + - MyINPulse-admin + description: 'Retrieves section cells belonging to a specific section of a project, filtered by the last modification date. Requires user to have access to the project.' parameters: - in: path - required: true name: projectId + required: true schema: type: integer + description: ID of the project. - in: path - required: true - description: 'this number can be 1, 2,...,8. It is associated with the title of the sectionCell' name: sectionId + required: true schema: type: integer - enum: - - 1 - - 2 - - 3 - - 4 - - 5 - - 6 - - 7 - - 8 + description: ID of the Lean Canvas section. - in: path - required: true name: date - description: the date corresponding to the wanted version of lc section. "Nan" for the latest version - example: NaN + required: true schema: type: string + format: date + description: The modification date to filter by (YYYY-MM-DD). responses: '200': - description: OK + description: OK - List of section cells matching the criteria. content: application/json: schema: @@ -350,192 +637,236 @@ paths: items: $ref: '#/components/schemas/sectionCell' '400': - description: Bad request + description: Bad Request - Invalid parameter format. '401': - description: Authorization information is missing or invalid + description: Unauthorized. '/shared/projects/entrepreneurs/{projectId}': get: - summary: Retourne la liste d'entrepreneurs associée à un projet donné + operationId: getProjectEntrepreneurs + summary: Get entrepreneurs associated with a project tags: - Shared API security: - MyINPulse: - - MyINPulse-admin - MyINPulse-entrepreneur - description: JSON array of entrepreneur names associated with a project + - MyINPulse-admin + description: Retrieves a list of entrepreneur users associated with the specified project. Requires access to the project. parameters: - in: path name: projectId + required: true schema: type: integer - required: true + description: ID of the project. responses: '200': - description: OK + description: OK - List of entrepreneurs. content: application/json: schema: type: array items: $ref: '#/components/schemas/user-entrepreneur' - '400': - description: Bad request '401': - description: Authorization information is missing or invalid - '/shared/projects/admin/{projectId}': + description: Unauthorized. + '403': + description: Forbidden - User does not have access to this project. + '404': + description: Not Found - Project not found. + '/shared/projects/admins/{projectId}': get: - summary: Retourne les informations de l'admin qui accompagne le projet + operationId: getProjectAdmins + summary: Get admins associated with a project tags: - Shared API security: - MyINPulse: - - MyINPulse-admin - MyINPulse-entrepreneur - description: 'JSON object containing information (name, gmail, tel, etc..) the admin supervising the project with id projectID.' + - MyINPulse-admin + description: Retrieves a list of admin users associated with the specified project. Requires access to the project. parameters: - in: path name: projectId + required: true schema: type: integer - required: true + description: ID of the project. responses: '200': - description: OK + description: OK - List of admins. content: application/json: schema: - $ref: '#/components/schemas/user-admin' - '400': - description: Bad request + type: array + items: + $ref: '#/components/schemas/user-admin' '401': - description: Authorization information is missing or invalid + description: Unauthorized. + '403': + description: Forbidden - User does not have access to this project. + '404': + description: Not Found - Project not found. '/shared/projects/appointments/{projectId}': get: - summary: Retourne les rendez-vous du projet + operationId: getProjectAppointments + summary: Get appointments related to a project tags: - Shared API security: - MyINPulse: - - MyINPulse-admin - MyINPulse-entrepreneur - description: JSON array of upcoming and past appointment data for the project with id projectID. + - MyINPulse-admin + description: Retrieves a list of appointments associated with the specified project. Requires access to the project. parameters: - in: path name: projectId + required: true schema: type: integer - required: true + description: ID of the project. responses: '200': - description: OK + description: OK - List of appointments. content: application/json: schema: type: array items: - $ref: '#/components/schemas/appointement' - '400': - description: Bad request + $ref: '#/components/schemas/appointment' '401': - description: Authorization information is missing or invalid - '/shared/projects/appointments/report/{appointmentId}': + description: Unauthorized. + '/shared/appointments/report/{appointmentId}': get: - summary: Retourne le rapport pdf du rendez-vous + operationId: getAppointmentReport + summary: Get the report for an appointment tags: - Shared API security: - MyINPulse: - - MyINPulse-admin - MyINPulse-entrepreneur - description: PDF file containing the ap- pointment report + - MyINPulse-admin + description: Retrieves the report associated with a specific appointment. Requires user to have access to the appointment/project. parameters: - in: path - name: apointementId + name: appointmentId + required: true schema: type: integer - required: true + description: ID of the appointment. responses: '200': - description: OK + description: OK - Report content returned. content: - application/pdf: + application/json: schema: - type: string - format: binary - '400': - description: Bad request + $ref: '#/components/schemas/report' '401': - description: Authorization information is missing or invalid + description: Unauthorized. /shared/appointments/request: post: - summary: demander un rendez-vous - description: will add an appointement request request by the applicant to have an appointment to be confirmed or denied by the specified participants of the appointement. + operationId: requestAppointment + summary: Request a new appointment tags: - Shared API security: - MyINPulse: - MyINPulse-entrepreneur - MyINPulse-admin + description: 'Allows a user (entrepreneur or admin) to request a new appointment, potentially with another user or regarding a project. Details in the body. The request might need confirmation or create a pending appointment.' requestBody: - description: \"participants\" property is an array containing userids of the participants in the appointement required: true + description: Details of the appointment request. content: application/json: schema: - type: object - properties: - title: - type: string - start_time: - type: string - end_time: - type: string - place: - type: string - applicantId: - type: integer - participants: - type: array - items: - type: integer + $ref: '#/components/schemas/appointment' + example: + value: + appointmentDate: '2025-06-01' + appointmentTime: '10:00:00' + appointmentDuration: PT1H + appointmentPlace: Online + appointmentSubject: Follow-up on prototype responses: - '200': - description: OK + '202': + description: Accepted - Appointment request submitted. + content: + application/json: + schema: + $ref: '#/components/schemas/appointment' '400': - description: Bad request + description: Bad Request - Invalid appointment details. '401': - description: Authorization information is missing or invalid + 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: - summary: demander la création et validation d'un projet + operationId: requestProjectCreation + summary: Request creation and validation of a new project tags: - Entrepreneurs API - description: Adds project to pending projects to then be accepted or rejected by an admin + description: |- + Submits a request for a new project. The project details are provided in the request body. + The requesting entrepreneur (identified by the token) will be associated to it. + The project is created with a 'pending' status, awaiting admin approval. security: - MyINPulse: - MyINPulse-entrepreneur requestBody: required: true + description: 'Project details for the request. `status`, `creationDate` are required by the model when being sent but is ignored by the server; primarily expects a valid `projectId`, `name`, `logo`.' content: application/json: schema: - type: object - properties: - name: - type: string - founder: - $ref: '#/components/schemas/user-entrepreneur' + $ref: '#/components/schemas/project' responses: - '200': - description: OK + '202': + description: Accepted - Project creation request received and is pending validation. '400': - description: Bad request + description: 'Bad Request - Invalid input (e.g., missing name).' '401': - description: Authorization information is missing or invalid - /entrepreneur/sectionCell/add: + 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: - summary: ajouter une sections au LC - description: Adds input data to the user's LC with a specified title. + operationId: addSectionCell + summary: Add a cell to a Lean Canvas section + description: Adds a new cell (like a sticky note) with the provided content to a specific section of the entrepreneur's project's Lean Canvas. Assumes project context is known based on user's token. `idSectionCell` and `modificationDate` are server-generated so they're values in the request are ignored by the server. tags: - Entrepreneurs API security: @@ -543,43 +874,23 @@ paths: - MyINPulse-entrepreneur requestBody: required: true + description: Section cell details. `idSectionCell` and `modificationDate` will be ignored if sent. content: application/json: schema: $ref: '#/components/schemas/sectionCell' responses: - '200': - description: OK + '201': + description: Created - Section cell added successfully. Returns the created cell. '400': - description: Bad request + description: 'Bad Request - Invalid input (e.g., missing content or sectionId).' '401': - description: Authorization information is missing or invalid - /entrepreneur/sectionCell/modify: + description: Unauthorized. + '/entrepreneur/sectionCells/{sectionCellId}': put: - summary: modifier les données d'une section LC - description: Modifies input Lean Canvas section by changing it to the information in the request body and changes the time stamp. - tags: - - Entrepreneurs API - security: - - MyINPulse: - - MyINPulse-entrepreneur - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/sectionCell' - responses: - '200': - description: OK - '400': - description: Bad request - '401': - description: Authorization information is missing or invalid - '/entrepreneur/sectionCell/remove/{sectionCellId}': - delete: - summary: supprimer une section LC. - description: Deletes section from Lean Canvas + 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`. tags: - Entrepreneurs API security: @@ -588,13 +899,46 @@ paths: parameters: - in: path name: sectionCellId + required: true schema: type: integer - required: true + description: The ID of the section cell to modify. + example: 508 + requestBody: + required: true + description: Updated section cell details. `idSectionCell` should match the path parameter. `modificationDate` will be updated by the server. + content: + application/json: + schema: + $ref: '#/components/schemas/sectionCell' responses: '200': - description: OK + description: OK - Section cell updated successfully. Returns the updated cell. '400': - description: Bad request + description: Bad Request - Invalid input or ID mismatch. '401': - description: Authorization information is missing or invalid + description: Unauthorized. + delete: + operationId: removeSectionCell + summary: Remove a Lean Canvas section cell + description: Deletes the Lean Canvas section cell specified by `sectionCellId`. + tags: + - Entrepreneurs API + security: + - MyINPulse: + - MyINPulse-entrepreneur + parameters: + - in: path + name: sectionCellId + required: true + schema: + type: integer + description: The ID of the section cell to remove. + example: 509 + responses: + '204': + description: No Content - Section cell removed successfully. + '400': + description: Bad Request - Invalid ID format. + '401': + description: Unauthorized. diff --git a/documentation/openapi/src/entrepreneurApi.yaml b/documentation/openapi/src/entrepreneurApi.yaml index 4fc3b82..6b14a1e 100644 --- a/documentation/openapi/src/entrepreneurApi.yaml +++ b/documentation/openapi/src/entrepreneurApi.yaml @@ -1,121 +1,143 @@ -# _____ _ _ _____ ____ _____ ____ ____ _____ _ _ _____ _ _ ____ -# | ____| \ | |_ _| _ \| ____| _ \| _ \| ____| \ | | ____| | | | _ \ -# | _| | \| | | | | |_) | _| | |_) | |_) | _| | \| | _| | | | | |_) | -# | |___| |\ | | | | _ <| |___| __/| _ <| |___| |\ | |___| |_| | _ < -# |_____|_|_\_| |_| |_| \_\_____|_| |_| \_\_____|_| \_|_____|\___/|_| \_\ -# / \ | _ \_ _| -# / _ \ | |_) | | -# / ___ \| __/| | -# /_/ \_\_| |___| -# - +# Entrepreneur API Endpoints paths: /entrepreneur/projects/request: post: - summary: demander la création et validation d'un projet + operationId: requestProjectCreation + summary: Request creation and validation of a new project tags: - Entrepreneurs API - description: - Adds project to pending projects - to then be accepted or rejected by - an admin + description: |- + Submits a request for a new project. The project details are provided in the request body. + The requesting entrepreneur (identified by the token) will be associated to it. + The project is created with a 'pending' status, awaiting admin approval. security: - - MyINPulse: - - MyINPulse-entrepreneur + - MyINPulse: [MyINPulse-entrepreneur] requestBody: required: true + description: Project details for the request. `status`, `creationDate` are required by the model when being sent but is ignored by the server; + primarily expects a valid `projectId`, `name`, `logo`. content: application/json: schema: - type: object - properties: - name: - type: string - founder: - $ref: "main.yaml#/components/schemas/user-entrepreneur" + $ref: "./main.yaml#/components/schemas/project" responses: - "200": - description: OK + "202": + description: Accepted - Project creation request received and is pending validation. "400": - description: Bad request + description: Bad Request - Invalid input (e.g., missing name). "401": - description: Authorization information is - missing or invalid - - - /entrepreneur/sectionCell/add: + 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: - summary: ajouter une sections au LC - description: - Adds input data to the user's LC - with a specified title. + 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 + - 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: + operationId: addSectionCell + summary: Add a cell to a Lean Canvas section + description: Adds a new cell (like a sticky note) with the provided content to a specific section of the entrepreneur's project's Lean Canvas. Assumes project context is known based on user's token. + `idSectionCell` and `modificationDate` are server-generated so they're values in the request are ignored by the server. + tags: + - Entrepreneurs API + security: + - MyINPulse: [MyINPulse-entrepreneur] requestBody: required: true + description: Section cell details. `idSectionCell` and `modificationDate` will be ignored if sent. content: application/json: schema: - $ref: "main.yaml#/components/schemas/sectionCell" + $ref: "./main.yaml#/components/schemas/sectionCell" responses: - "200": - description: OK + "201": + description: Created - Section cell added successfully. Returns the created cell. "400": - description: Bad request + description: Bad Request - Invalid input (e.g., missing content or sectionId). "401": - description: Authorization information is - missing or invalid - /entrepreneur/sectionCell/modify: + description: Unauthorized. + + /entrepreneur/sectionCells/{sectionCellId}: put: - summary: modifier les données d'une section LC - description: - Modifies input Lean Canvas section by changing it to - the information in the request body and changes the - time stamp. + 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`. tags: - Entrepreneurs API security: - - MyINPulse: - - MyINPulse-entrepreneur - requestBody: - required: true - content: - application/json: - schema: - $ref: "main.yaml#/components/schemas/sectionCell" - responses: - "200": - description: OK - "400": - description: Bad request - "401": - description: Authorization information is - missing or invalid - - /entrepreneur/sectionCell/remove/{sectionCellId}: - delete: - summary: supprimer une section LC. - description: - Deletes section from Lean Canvas - tags: - - Entrepreneurs API - security: - - MyINPulse: - - MyINPulse-entrepreneur + - MyINPulse: [MyINPulse-entrepreneur] parameters: - in: path name: sectionCellId + required: true schema: type: integer - required: true + description: The ID of the section cell to modify. + example: 508 + requestBody: + required: true + description: Updated section cell details. `idSectionCell` should match the path parameter. `modificationDate` will be updated by the server. + content: + application/json: + schema: + $ref: "./main.yaml#/components/schemas/sectionCell" responses: - "200": - description: OK + "200": + description: OK - Section cell updated successfully. Returns the updated cell. "400": - description: Bad request + description: Bad Request - Invalid input or ID mismatch. "401": - description: Authorization information is - missing or invalid \ No newline at end of file + description: Unauthorized. + + delete: + operationId: removeSectionCell + summary: Remove a Lean Canvas section cell + description: Deletes the Lean Canvas section cell specified by `sectionCellId`. + tags: + - Entrepreneurs API + security: + - MyINPulse: [MyINPulse-entrepreneur] + parameters: + - in: path + name: sectionCellId + required: true + schema: + type: integer + description: The ID of the section cell to remove. + example: 509 + responses: + "204": + description: No Content - Section cell removed successfully. + "400": + description: Bad Request - Invalid ID format. + "401": + description: Unauthorized. \ No newline at end of file diff --git a/documentation/openapi/src/main.yaml b/documentation/openapi/src/main.yaml index 2d666ec..ceadc8e 100644 --- a/documentation/openapi/src/main.yaml +++ b/documentation/openapi/src/main.yaml @@ -1,17 +1,18 @@ openapi: 3.0.3 info: - title: MyInpulse Backend Api - description: this document servers as a documentation for the backend api. - version: 0.2.0 + title: MyInpulse Backend API + description: This serves as an OpenAPI documentation for the MyInpulse backend service, covering operations for Entrepreneurs, Admins, and shared functionalities. + version: 0.2.1 tags: - name: Entrepreneurs API - description: La partie de l'api dédiée aux entrepreneurs + description: API endpoints primarily for Entrepreneur users. - name: Admin API - description: La partie de l'api dédiée aux entrepreneurs + description: API endpoints restricted to Admin users for management tasks. - name: Shared API - description: La partie de l'api dédiée aux entrepreneurs et admins - + description: API endpoints accessible by both Entrepreneurs and Admins. + - name: Account Management API + description: API endpoints related to user account management. components: schemas: @@ -27,88 +28,137 @@ components: $ref: "models.yaml#/project" report: $ref: "models.yaml#/report" - appointement: - $ref: "models.yaml#/appointement" - + appointment: + $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 securitySchemes: MyINPulse: type: oauth2 + description: OAuth2 authentication using Keycloak. flows: implicit: - authorizationUrl: http://localhost:7080 + authorizationUrl: '{keycloakBaseUrl}/realms/{keycloakRealm}/protocol/openid-connect/auth' scopes: - MyINPulse-admin: Administrateur - MyINPulse-entrepreneur: Utilisateur + MyINPulse-admin: Grants administrator access. + MyINPulse-entrepreneur: Grants standard entrepreneur user access. servers: - - url: http://localhost:8081/ - description: Backend server - - + - url: '{serverProtocol}://{serverHost}:{serverPort}' + description: API Server Environment + variables: + serverProtocol: + enum: [http, https] + default: http + serverHost: + default: localhost + serverPort: + enum: ['8081'] + default: '8081' + keycloakBaseUrl: + default: http://localhost:7080 + description: Base URL for the Keycloak server. + keycloakRealm: + default: MyInpulseRealm + description: Keycloak realm name. paths: - # _ ____ __ __ ___ _ _ _ ____ ___ + # _ _ _ _ _ _ + # | | | |_ __ __ _ _ _| |_| |__ / \ _ __ (_) + # | | | | '_ \ / _` | | | | __| '_ \ / _ \ | '_ \| | + # | |_| | | | | (_| | |_| | |_| | | |/ ___ \| |_) | | + # \___/|_| |_|\__,_|\__,_|\__|_| |_/_/ \_\ .__/|_| + # |_| + + /accounts/finalize: + $ref: "./unauthApi.yaml#/paths/~1accounts~1finalize" + + # _ ____ __ __ ___ _ _ _ ____ ___ # / \ | _ \| \/ |_ _| \ | | / \ | _ \_ _| - # / _ \ | | | | |\/| || || \| | / _ \ | |_) | | - # / ___ \| |_| | | | || || |\ | / ___ \| __/| | + # / _ \ | | | | |\/| || || \| | / _ \ | |_) | | + # / ___ \| |_| | | | || || |\ | / ___ \| __/| | # /_/ \_\____/|_| |_|___|_| \_| /_/ \_\_| |___| # + /admin/pending-accounts: + $ref: "./adminApi.yaml#/paths/~1admin~1pending-accounts" + /admin/accounts/validate/{userId}: + $ref: "./adminApi.yaml#/paths/~1admin~1accounts~1validate~1{userId}" /admin/projects: $ref: "./adminApi.yaml#/paths/~1admin~1projects" - /admin/projects/pending/decision: - $ref: "./adminApi.yaml#/paths/~1admin~1projects~1pending~1decision" - /admin/projects/add: - $ref: "./adminApi.yaml#/paths/~1admin~1projects~1add" - /admin/appointments/report/{appointmentId}: - $ref: "./adminApi.yaml#/paths/~1admin~1appointments~1report~1{appointmentId}" - /admin/projects/remove/{projectId}: - $ref: "./adminApi.yaml#/paths/~1admin~1projects~1remove~1{projectId}" /admin/projects/pending: $ref: "./adminApi.yaml#/paths/~1admin~1projects~1pending" + /admin/projects/pending/decision/{pendingProjectId}: + $ref: "./adminApi.yaml#/paths/~1admin~1projects~1pending~1decision~1{pendingProjectId}" + /admin/appointments/report/{appointmentId}: + $ref: "./adminApi.yaml#/paths/~1admin~1appointments~1report~1{appointmentId}" + /admin/projects/{projectId}: + $ref: "./adminApi.yaml#/paths/~1admin~1projects~1{projectId}" + /admin/make-admin/{userId}: # Renamed for clarity + $ref: "./adminApi.yaml#/paths/~1admin~1make-admin~1{userId}" - # ____ _ _ _ ____ ___ + # ____ _ _ _ ____ ___ # / ___|| |__ __ _ _ __ ___ __| | / \ | _ \_ _| - # \___ \| '_ \ / _` | '__/ _ \/ _` | / _ \ | |_) | | - # ___) | | | | (_| | | | __/ (_| | / ___ \| __/| | + # \___ \| '_ \ / _` | '__/ _ \/ _` | / _ \ | |_) | | + # ___) | | | | (_| | | | __/ (_| | / ___ \| __/| | # |____/|_| |_|\__,_|_| \___|\__,_| /_/ \_\_| |___| - # + # /shared/appointments/upcoming: $ref: "./sharedApi.yaml#/paths/~1shared~1appointments~1upcoming" - /shared/projects/sectionCell/{projectId}/{sectionId}/{date}: - $ref: "./sharedApi.yaml#/paths/~1shared~1projects~1sectionCell~1{projectId}~1{sectionId}~1{date}" + /shared/projects/sectionCells/{projectId}/{sectionId}/{date}: + $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/admin/{projectId}: - $ref: "./sharedApi.yaml#/paths/~1shared~1projects~1admin~1{projectId}" + /shared/projects/admins/{projectId}: + $ref: "./sharedApi.yaml#/paths/~1shared~1projects~1admins~1{projectId}" /shared/projects/appointments/{projectId}: $ref: "./sharedApi.yaml#/paths/~1shared~1projects~1appointments~1{projectId}" - /shared/projects/appointments/report/{appointmentId}: - $ref: "./sharedApi.yaml#/paths/~1shared~1projects~1appointments~1report~1{appointmentId}" - + /shared/appointments/report/{appointmentId}: + $ref: "./sharedApi.yaml#/paths/~1shared~1appointments~1report~1{appointmentId}" /shared/appointments/request: $ref: "./sharedApi.yaml#/paths/~1shared~1appointments~1request" - # _____ _ _ _____ ____ _____ ____ ____ _____ _ _ _____ _ _ ____ - # | ____| \ | |_ _| _ \| ____| _ \| _ \| ____| \ | | ____| | | | _ \ + # _____ _ _ _____ ____ _____ ____ ____ _____ _ _ _____ _ _ ____ + # | ____| \ | |_ _| _ \| ____| _ \| _ \| ____| \ | | ____| | | | _ \ # | _| | \| | | | | |_) | _| | |_) | |_) | _| | \| | _| | | | | |_) | - # | |___| |\ | | | | _ <| |___| __/| _ <| |___| |\ | |___| |_| | _ < + # | |___| |\ | | | | _ <| |___| __/| _ <| |___| |\ | |___| |_| | _ < # |_____|_|_\_| |_| |_| \_\_____|_| |_| \_\_____|_| \_|_____|\___/|_| \_\ - # / \ | _ \_ _| - # / _ \ | |_) | | - # / ___ \| __/| | - # /_/ \_\_| |___| + # / \ | _ \_ _| + # / _ \ | |_) | | + # / ___ \| __/| | + # /_/ \_\_| |___| # + /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/sectionCell/add: - $ref: "./entrepreneurApi.yaml#/paths/~1entrepreneur~1sectionCell~1add" - /entrepreneur/sectionCell/modify: - $ref: "./entrepreneurApi.yaml#/paths/~1entrepreneur~1sectionCell~1modify" - /entrepreneur/sectionCell/remove/{sectionCellId}: - $ref: "./entrepreneurApi.yaml#/paths/~1entrepreneur~1sectionCell~1remove~1{sectionCellId}" - - - - - \ No newline at end of file + /entrepreneur/sectionCells: + $ref: "./entrepreneurApi.yaml#/paths/~1entrepreneur~1sectionCells" + /entrepreneur/sectionCells/{sectionCellId}: + $ref: "./entrepreneurApi.yaml#/paths/~1entrepreneur~1sectionCells~1{sectionCellId}" \ No newline at end of file diff --git a/documentation/openapi/src/models.yaml b/documentation/openapi/src/models.yaml index 68d1fc7..1c165b4 100644 --- a/documentation/openapi/src/models.yaml +++ b/documentation/openapi/src/models.yaml @@ -1,92 +1,183 @@ # models.yaml - user: - type: object - properties: - idUser: - type: integer - userSurname: - type: string - userName: - type: string - primaryMail: - type: string - example: "example@exmaple.com" - secondaryMail: - type: string - example: "example@exmaple.com" - phoneNumber: - type: string - example: "0612345678" - + type: object + properties: + idUser: + type: integer + description: Unique identifier for the user. + #readOnly: true # Typically generated by the server + example: 101 + userSurname: + type: string + description: User's surname (last name). + example: "Doe" + userName: + type: string + description: User's given name (first name). + example: "John" + primaryMail: + type: string + format: email + description: User's primary email address. + example: "john.doe@example.com" + secondaryMail: + type: string + format: email + description: User's secondary email address (optional). + example: "j.doe@personal.com" + phoneNumber: + type: string + description: User's phone number. + example: "+33612345678" # Example using international format + user-entrepreneur: allOf: - $ref: "#/user" - type: object - properties: - school: + properties: + school: type: string - example: "enseirb" + description: The school the entrepreneur attends/attended. + example: "ENSEIRB-MATMECA" course: type: string - example: "info" + description: The specific course or program of study. + example: "Electronics" sneeStatus: type: boolean - example: false + description: Indicates if the user has SNEE status (Statut National d'Étudiant-Entrepreneur). + example: true + example: # Added full object example + idUser: 101 + userSurname: "Doe" + userName: "John" + primaryMail: "john.doe@example.com" + secondaryMail: "j.doe@personal.com" + phoneNumber: "+33612345678" + school: "ENSEIRB-MATMECA" + course: "Electronics" + sneeStatus: true user-admin: allOf: - $ref: "#/user" + # No additional properties needed for this example + example: # Added full object example + idUser: 55 + userSurname: "Admin" + userName: "Super" + primaryMail: "admin@myinpulse.com" + phoneNumber: "+33512345678" sectionCell: type: object + description: Represents a cell (like a sticky note) within a specific section of a project's Lean Canvas. properties: idSectionCell: type: integer - example: this the cell (postit id) + description: Unique identifier for the section cell. + #readOnly: true # Generated by server + example: 508 sectionId: type: integer + description: Identifier of the Lean Canvas section this cell belongs to (e.g., 1 for Problem, 2 for Solution). + example: 1 contentSectionCell: type: string + description: The text content of the section cell. + example: "Users find it hard to track project progress." modificationDate: type: string - example: "02-05-2025" + 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" project: type: object + description: Represents a project being managed or developed. properties: idProject: type: integer + description: Unique identifier for the project. + #readOnly: true # Generated by server + example: 12 projectName: type: string + description: The name of the project. + example: "MyInpulse Mobile App" creationDate: type: string - example: "02-05-2025" + 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" logo: - example: to be discussed not yet fixed type: string - format: binary + format: byte + description: Base64 encoded string representing the project logo image. + example: "/*Base64 encoded string representing the project logo image*/" + status: + type: string + enum: [PENDING, ACTIVE, ENDED, ABORTED, REJECTED] + description: Corresponds to a status enum internal to the backend, it's value in in requests + incoming to the server should be ignored as the client shouldn't be specifying them. + example: "NaN" report: type: object + description: Represents a report associated with an appointment. properties: idReport: type: integer + description: Unique identifier for the report. + #readOnly: true # Generated by server + example: 987 reportContent: type: string - -appointement: + description: The textual content of the report. Could be plain text or Markdown (specify if known). + example: "Discussed roadmap milestones for Q3. Agreed on preliminary UI mockups." + +appointment: # Corrected typo type: object + description: Represents a scheduled meeting or appointment. properties: + idAppointment: # Assuming there's an ID + type: integer + description: Unique identifier for the appointment. + #readOnly: true + example: 303 appointmentDate: type: string - example: "02-05-2025" + format: date # Using Java LocalDate -> YYYY-MM-DD + description: The date of the appointment. + example: "2025-05-10" appointmentTime: type: string - example: "10:15:30" + format: time # Using Java LocalTime -> HH:mm:ss + description: The time of the appointment (local time). + example: "14:30:00" appointmentDuration: type: string + description: Duration of the appointment in ISO 8601 duration format (e.g., PT1H30M for 1 hour 30 minutes). + example: "PT1H" # Example for 1 hour appointmentPlace: type: string + description: Location or meeting link for the appointment. + example: "Meeting Room 3 / https://meet.example.com/abc-def-ghi" appointmentSubject: - type: string \ No newline at end of file + type: string + description: The main topic or subject of the appointment. + 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 \ No newline at end of file diff --git a/documentation/openapi/src/sharedApi.yaml b/documentation/openapi/src/sharedApi.yaml index 79fe139..d600cf7 100644 --- a/documentation/openapi/src/sharedApi.yaml +++ b/documentation/openapi/src/sharedApi.yaml @@ -1,254 +1,218 @@ -# ____ _ _ _ ____ ___ -# / ___|| |__ __ _ _ __ ___ __| | / \ | _ \_ _| -# \___ \| '_ \ / _` | '__/ _ \/ _` | / _ \ | |_) | | -# ___) | | | | (_| | | | __/ (_| | / ___ \| __/| | -# |____/|_| |_|\__,_|_| \___|\__,_| /_/ \_\_| |___| -# +# Shared API Endpoints paths: /shared/appointments/upcoming: get: - summary: Retourne la list des prochains rendez-vous de l'utilisateur - tags: - - Shared API - security: - - MyINPulse: - - MyINPulse-admin - - MyINPulse-entrepreneur - description: - JSON array of upcoming appointment data (name, date, time etc..) for a user. - responses: - "200": - description: OK - content: - application/json: - schema: - type: array - items: - $ref: "main.yaml#/components/schemas/appointement" - "400": - description: Bad request - "401": - description: Authorization information is missing or invalid - - /shared/projects/sectionCell/{projectId}/{sectionId}/{date}: - get: - summary: Retourne la liste de sections de LC avec un titre donné - tags: - - Shared API - security: - - MyINPulse: - - MyINPulse-admin - - MyINPulse-entrepreneur - description: - JSON array containing Lean Canvas - section data with a title for the - current date (or given date if the - date parameter is passed) - parameters: - - in: path - required: true - name: projectId - schema: - type: integer - - in: path - required: true - description: this number can be 1, 2,...,8. It is associated with the title of the sectionCell - name: sectionId - schema: - type: integer - enum: [1, 2, 3, 4, 5, 6, 7, 8] - - in: path - required: true - name: date - description: the date corresponding to the wanted version of lc section. "Nan" for the latest version - example: "NaN" - schema: - type: string - - responses: - "200": - description: OK - content: - application/json: - schema: - type: array - items: - $ref: "main.yaml#/components/schemas/sectionCell" - "400": - description: Bad request - "401": - description: Authorization information is missing or invalid - - /shared/projects/entrepreneurs/{projectId}: - get: - summary: Retourne la liste d'entrepreneurs associée à un projet donné - tags: - - Shared API - security: - - MyINPulse: - - MyINPulse-admin - - MyINPulse-entrepreneur - description: - JSON array of entrepreneur - names associated with a project - parameters: - - in: path - name: projectId - schema: - type: integer - required: true - responses: - "200": - description: OK - content: - application/json: - schema: - type: array - items: - $ref: "main.yaml#/components/schemas/user-entrepreneur" - "400": - description: Bad request - "401": - description: Authorization information is missing or invalid - - /shared/projects/admin/{projectId}: - get: - summary: Retourne les informations de l'admin qui accompagne le projet - tags: - - Shared API - security: - - MyINPulse: - - MyINPulse-admin - - MyINPulse-entrepreneur - description: - JSON object containing information (name, gmail, tel, etc..) - the admin supervising the project with id projectID. - parameters: - - in: path - name: projectId - schema: - type: integer - required: true - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "main.yaml#/components/schemas/user-admin" - "400": - description: Bad request - "401": - description: Authorization information is - missing or invalid - - /shared/projects/appointments/{projectId}: - get: - summary: Retourne les rendez-vous du projet - tags: - - Shared API - security: - - MyINPulse: - - MyINPulse-admin - - MyINPulse-entrepreneur - description: - JSON array of upcoming and past appointment - data for the project with id projectID. - parameters: - - in: path - name: projectId - schema: - type: integer - required: true - responses: - "200": - description: OK - content: - application/json: - schema: - type: array - items: - $ref: "main.yaml#/components/schemas/appointement" - "400": - description: Bad request - "401": - description: Authorization information is - missing or invalid - /shared/projects/appointments/report/{appointmentId}: - get: - summary: Retourne le rapport pdf du rendez-vous - tags: - - Shared API - security: - - MyINPulse: - - MyINPulse-admin - - MyINPulse-entrepreneur - description: - PDF file containing the ap- - pointment report - parameters: - - in: path - name: apointementId - schema: - type: integer - required: true - responses: - "200": - description: OK - content: - application/pdf: - schema: - type: string - format: binary - "400": - description: Bad request - "401": - description: Authorization information is - missing or invalid - - /shared/appointments/request: - post: - summary: demander un rendez-vous - description: - will add an appointement request request by the applicant - to have an appointment to be confirmed or denied by the - specified participants of the appointement. + operationId: getUpcomingAppointments + summary: Get upcoming appointments for the user tags: - Shared API security: - - MyINPulse: - - MyINPulse-entrepreneur - - MyINPulse-admin + - MyINPulse: [MyINPulse-entrepreneur, MyINPulse-admin] # Accessible by both + description: Retrieves a list of appointments scheduled for the authenticated user (either entrepreneur or admin) in the future. + responses: + "200": + description: OK - List of upcoming appointments. + content: + application/json: + schema: + type: array + items: + $ref: "./main.yaml#/components/schemas/appointment" + "401": + description: Unauthorized. + + + /shared/projects/sectionCells/{projectId}/{sectionId}/{date}: + get: + operationId: getSectionCellsByDate + summary: Get project section cells modified on a specific date + tags: + - Shared API + security: + - MyINPulse: [MyINPulse-entrepreneur, MyINPulse-admin] + description: Retrieves section cells belonging to a specific section of a project, filtered by the last modification date. Requires user to have access to the project. + parameters: + - in: path + name: projectId + required: true + schema: { type: integer } + description: ID of the project. + - in: path + name: sectionId + required: true + schema: { type: integer } + description: ID of the Lean Canvas section. + - in: path + name: date + required: true + schema: { type: string, format: date } # Expect YYYY-MM-DD + description: The modification date to filter by (YYYY-MM-DD). + responses: + "200": + description: OK - List of section cells matching the criteria. + content: + application/json: + schema: + type: array + items: + $ref: "./main.yaml#/components/schemas/sectionCell" + "400": + description: Bad Request - Invalid parameter format. + "401": + description: Unauthorized. + + + /shared/projects/entrepreneurs/{projectId}: + get: + operationId: getProjectEntrepreneurs + summary: Get entrepreneurs associated with a project + tags: + - Shared API + security: + - MyINPulse: [MyINPulse-entrepreneur, MyINPulse-admin] + description: Retrieves a list of entrepreneur users associated with the specified project. Requires access to the project. + parameters: + - in: path + name: projectId + required: true + schema: { type: integer } + description: ID of the project. + responses: + "200": + description: OK - List of entrepreneurs. + content: + application/json: + schema: + type: array + items: + $ref: "./main.yaml#/components/schemas/user-entrepreneur" + "401": + description: Unauthorized. + "403": + description: Forbidden - User does not have access to this project. + "404": + description: Not Found - Project not found. + + /shared/projects/admins/{projectId}: # Path updated + get: + operationId: getProjectAdmins + summary: Get admins associated with a project + tags: + - Shared API + security: + - MyINPulse: [MyINPulse-entrepreneur, MyINPulse-admin] + description: Retrieves a list of admin users associated with the specified project. Requires access to the project. + parameters: + - in: path + name: projectId + required: true + schema: { type: integer } + description: ID of the project. + responses: + "200": + description: OK - List of admins. + content: + application/json: + schema: + type: array + items: + $ref: "./main.yaml#/components/schemas/user-admin" + "401": + description: Unauthorized. + "403": + description: Forbidden - User does not have access to this project. + "404": + description: Not Found - Project not found. + + + /shared/projects/appointments/{projectId}: + get: + operationId: getProjectAppointments + summary: Get appointments related to a project + tags: + - Shared API + security: + - MyINPulse: [MyINPulse-entrepreneur, MyINPulse-admin] + description: Retrieves a list of appointments associated with the specified project. Requires access to the project. + parameters: + - in: path + name: projectId + required: true + schema: { type: integer } + description: ID of the project. + responses: + "200": + description: OK - List of appointments. + content: + application/json: + schema: + type: array + items: + $ref: "./main.yaml#/components/schemas/appointment" + "401": + description: Unauthorized. + + + /shared/appointments/report/{appointmentId}: # Path updated + get: + operationId: getAppointmentReport # Shared endpoint implies read-only access might be possible + summary: Get the report for an appointment + tags: + - Shared API + security: + - MyINPulse: [MyINPulse-entrepreneur, MyINPulse-admin] + description: Retrieves the report associated with a specific appointment. Requires user to have access to the appointment/project. + parameters: + - in: path + name: appointmentId + required: true + schema: { type: integer } + description: ID of the appointment. + responses: + "200": + description: OK - Report content returned. + content: + application/json: + schema: + $ref: "./main.yaml#/components/schemas/report" + "401": + description: Unauthorized. + + + /shared/appointments/request: + post: + operationId: requestAppointment + summary: Request a new appointment + tags: + - Shared API + security: + - MyINPulse: [MyINPulse-entrepreneur, MyINPulse-admin] + description: Allows a user (entrepreneur or admin) to request a new appointment, potentially with another user or regarding a project. Details in the body. The request might need confirmation or create a pending appointment. requestBody: - description: \"participants\" property is an array containing userids of the participants in the appointement required: true + description: Details of the appointment request. content: application/json: schema: - type: object - properties: - title: - type: string - start_time: - type: string - end_time: - type: string - place: - type: string - applicantId: - type: integer - participants: - #/* */ - type: array - items: - type: integer - + $ref: "./main.yaml#/components/schemas/appointment" # Assuming request uses same model structure + example: + value: + appointmentDate: "2025-06-01" + appointmentTime: "10:00:00" + appointmentDuration: "PT1H" + appointmentPlace: "Online" + appointmentSubject: "Follow-up on prototype" + # Potentially add projectId or targetUserId here responses: - "200": - description: OK + "202": # Accepted seems appropriate for a request + description: Accepted - Appointment request submitted. + content: + application/json: # Optionally return the pending appointment data + schema: + $ref: "./main.yaml#/components/schemas/appointment" "400": - description: Bad request + description: Bad Request - Invalid appointment details. + "401": - description: Authorization information is - missing or invalid - \ No newline at end of file + description: Unauthorized. + \ No newline at end of file diff --git a/documentation/openapi/src/unauthApi.yaml b/documentation/openapi/src/unauthApi.yaml new file mode 100644 index 0000000..c9676f6 --- /dev/null +++ b/documentation/openapi/src/unauthApi.yaml @@ -0,0 +1,34 @@ + +# _ _ _ _ _ _ +# | | | |_ __ __ _ _ _| |_| |__ / \ _ __ (_) +# | | | | '_ \ / _` | | | | __| '_ \ / _ \ | '_ \| | +# | |_| | | | | (_| | |_| | |_| | | |/ ___ \| |_) | | +# \___/|_| |_|\__,_|\__,_|\__|_| |_/_/ \_\ .__/|_| +# |_| + +paths: + /accounts/finalize: # Path renamed from /unauth/create_account + post: + operationId: finalizeAccountSetup # Renamed operationId + summary: Finalize account setup using authentication token + description: |- + Completes the user account creation/setup process in the MyInpulse system. + This endpoint requires the user to be authenticated via Keycloak (e.g., after initial login). + 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 + responses: + "201": # Use 201 Created or 200 OK if it returns the user profile + 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