From 20bca794724ce1dc22591361ce8419aa66564114 Mon Sep 17 00:00:00 2001
From: MAILLAL Anas <Anas.Maillal@bordeaux-inp.fr>
Date: Mon, 21 Apr 2025 10:51:15 +0200
Subject: [PATCH] feat: added doc for upcoming endpoints to finish up
entrepreneur join, response codes remaining to update
---
documentation/openapi/src/adminApi.yaml | 60 ++++++++++-
documentation/openapi/src/bundled.yaml | 102 ++++++++++++++----
.../openapi/src/entrepreneurApi.yaml | 4 +-
documentation/openapi/src/main.yaml | 8 +-
documentation/openapi/src/models.yaml | 36 ++++---
documentation/openapi/src/sharedApi.yaml | 16 +--
6 files changed, 179 insertions(+), 47 deletions(-)
diff --git a/documentation/openapi/src/adminApi.yaml b/documentation/openapi/src/adminApi.yaml
index 8c113e5..9a7a977 100644
--- a/documentation/openapi/src/adminApi.yaml
+++ b/documentation/openapi/src/adminApi.yaml
@@ -8,7 +8,7 @@ paths:
- Admin API
security:
- MyINPulse: [MyINPulse-admin]
- description: Retrieves a list of projects managed by the requesting admin, including key details for overview.
+ description: Retrieves a list of projects managed by the requesting admin, including details for overview.
responses:
"200":
description: OK - List of projects returned successfully.
@@ -26,7 +26,7 @@ paths:
post:
operationId: addProjectManually
summary: Manually add a new project
- description: Creates a new project with the provided details.
+ description: Creates a new project with the provided details. (NOTE that this meant for manually inserting projects, for example importing already existing projects).
tags:
- Admin API
security:
@@ -72,6 +72,58 @@ paths:
"401":
description: Unauthorized.
+ /admin/request-join:
+ get:
+ operationId: getPendingProjects
+ summary: Get entrepreneurs project join requests
+ tags:
+ - Admin API
+ security:
+ - MyINPulse: [MyINPulse-admin]
+ description: Retrieves a list of pending requests from entrepreneurs to join an existing project.
+ responses:
+ "200":
+ description: OK - List of pending project join requests.
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "./main.yaml#/components/schemas/joinRequest"
+ "401":
+ description: Unauthorized.
+
+ /admin/request-join/decision/{joinRequestId}:
+ post:
+ summary: Approve or reject a pending project join request
+ tags:
+ - Admin API
+ security:
+ - MyINPulse: [MyINPulse-admin]
+ parameters:
+ - in: path
+ name: joinRequestId
+ required: true
+ schema:
+ type: integer
+ description: The ID of the pending join request to decide upon.
+
+ description: |-
+ Allows an admin to make a decision on an ebtrepreneur's request to join an existing project awaiting validation.
+ If approved (isAccepted=true), the entrepreneur is linked to the project with ID joinRequestId.
+ If rejected (isAccepted=false), the pending request data might be archived or deleted based on business logic.
+ responses:
+ "200":
+ description: OK - No Content, decision processed successfully..
+ content:
+ application/json:
+ $ref: "./main.yaml#/components/schemas/joinRequestDecision"
+ "400":
+ description: Bad Request - Invalid input (e.g., missing decision).
+ "401":
+ description: Unauthorized.
+
+
/admin/projects/pending/decision/{pendingProjectId}:
post:
operationId: decidePendingProject
@@ -80,8 +132,8 @@ paths:
- Admin API
description: |-
Allows an admin to make a decision on a project awaiting validation.
- If approved (decision=true), the project status changes, and it's linked to the involved users.
- If rejected (decision=false), the pending project data might be archived or deleted based on business logic.
+ If approved (isAccepted=true), the project status changes, and it's linked to the involved users.
+ If rejected (isAccepted=false), the pending project data might be archived or deleted based on business logic.
security:
- MyINPulse: [MyINPulse-admin]
parameters:
diff --git a/documentation/openapi/src/bundled.yaml b/documentation/openapi/src/bundled.yaml
index 1717edf..6be8cf3 100644
--- a/documentation/openapi/src/bundled.yaml
+++ b/documentation/openapi/src/bundled.yaml
@@ -99,7 +99,7 @@ components:
type: string
format: date
description: The date when this cell was last modified.
- example: '2025-04-15'
+ example: 'yyyy-MM-dd HH:mm'
project:
type: object
description: Represents a project being managed or developed.
@@ -116,7 +116,7 @@ components:
type: string
format: date
description: The date when the project was created in the system.
- example: '2024-11-20'
+ example: 'yyyy-MM-dd HH:mm'
logo:
type: string
format: byte
@@ -176,12 +176,14 @@ components:
example: Q3 Roadmap Planning
joinRequest:
type: object
- description: Represents a request from an entrepreneur to join an existing project.
+ description: Represents a request from an entrepreneur to join an already existing project.
properties:
- projectId:
+ idProject:
type: integer
- description: The ID of the project the entrepreneur wants to join.
- example: 12
+ description: the ID of the project the entrepreneur wants to join.
+ example: 42
+ entrepreneur:
+ $ref: '#/components/schemas/user-entrepreneur'
projectDecision:
type: object
description: Represents a decision from an admin to accept a pending project.
@@ -198,6 +200,14 @@ components:
type: boolean
description: The boolean value of the decision.
example: 'true'
+ joinRequestDecision:
+ type: object
+ description: Represents a decision from an admin to accept a pending project join request.
+ properties:
+ isAccepted:
+ type: boolean
+ description: The boolean value of the decision.
+ example: 'true'
securitySchemes:
MyINPulse:
type: oauth2
@@ -210,7 +220,7 @@ components:
MyINPulse-entrepreneur: Grants standard entrepreneur user access.
servers:
- url: '{serverProtocol}://{serverHost}:{serverPort}'
- description: API Server Environment
+ description: API Server
variables:
serverProtocol:
enum:
@@ -314,6 +324,56 @@ paths:
description: Bad Request - Invalid user ID format.
'401':
description: Unauthorized.
+ /admin/request-join:
+ get:
+ operationId: getPendingProjects
+ summary: Get entrepreneurs project join requests
+ tags:
+ - Admin API
+ security:
+ - MyINPulse:
+ - MyINPulse-admin
+ description: Retrieves a list of pending requests from entrepreneurs to join an existing project.
+ responses:
+ '200':
+ description: OK - List of pending project join requests.
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: '#/components/schemas/joinRequest'
+ '401':
+ description: Unauthorized.
+ '/admin/request-join/decision/{joinRequestId}':
+ post:
+ summary: Approve or reject a pending project join request
+ tags:
+ - Admin API
+ security:
+ - MyINPulse:
+ - MyINPulse-admin
+ parameters:
+ - in: path
+ name: joinRequestId
+ required: true
+ schema:
+ type: integer
+ description: The ID of the pending join request to decide upon.
+ description: |-
+ Allows an admin to make a decision on an ebtrepreneur's request to join an existing project awaiting validation.
+ If approved (isAccepted=true), the entrepreneur is linked to the project with ID joinRequestId.
+ If rejected (isAccepted=false), the pending request data might be archived or deleted based on business logic.
+ responses:
+ '200':
+ description: 'OK - No Content, decision processed successfully..'
+ content:
+ application/json:
+ $ref: '#/components/schemas/joinRequestDecision'
+ '400':
+ description: 'Bad Request - Invalid input (e.g., missing decision).'
+ '401':
+ description: Unauthorized.
/admin/projects:
get:
operationId: getAdminProjects
@@ -323,7 +383,7 @@ paths:
security:
- MyINPulse:
- MyINPulse-admin
- description: 'Retrieves a list of projects managed by the requesting admin, including key details for overview.'
+ description: 'Retrieves a list of projects managed by the requesting admin, including details for overview.'
responses:
'200':
description: OK - List of projects returned successfully.
@@ -340,7 +400,7 @@ paths:
post:
operationId: addProjectManually
summary: Manually add a new project
- description: Creates a new project with the provided details.
+ description: 'Creates a new project with the provided details. (NOTE that this meant for manually inserting projects, for example importing already existing projects).'
tags:
- Admin API
security:
@@ -393,8 +453,8 @@ paths:
- Admin API
description: |-
Allows an admin to make a decision on a project awaiting validation.
- If approved (decision=true), the project status changes, and it's linked to the involved users.
- If rejected (decision=false), the pending project data might be archived or deleted based on business logic.
+ If approved (isAccepted=true), the project status changes, and it's linked to the involved users.
+ If rejected (isAccepted=false), the pending project data might be archived or deleted based on business logic.
security:
- MyINPulse:
- MyINPulse-admin
@@ -593,7 +653,7 @@ paths:
schema:
type: string
format: date
- description: The modification date to filter by (YYYY-MM-DD).
+ description: 'The modification date to filter by (YYYY-MM-DD HH:mm).'
responses:
'200':
description: OK - List of section cells matching the criteria.
@@ -642,8 +702,8 @@ paths:
description: Not Found - Project not found.
'/shared/projects/admin/{projectId}':
get:
- operationId: getProjectAdmins
- summary: Get admins associated with a project
+ operationId: getProjectAdmin
+ summary: Get admin associated with a project
tags:
- Shared API
security:
@@ -660,7 +720,7 @@ paths:
description: ID of the project.
responses:
'200':
- description: OK - List of admins.
+ description: OK - admin.
content:
application/json:
schema:
@@ -720,11 +780,13 @@ paths:
description: ID of the appointment.
responses:
'200':
- description: OK - Report content returned.
+ description: OK - Report PDF returned.
content:
- application/json:
+ application/pdf:
schema:
- $ref: '#/components/schemas/report'
+ schema: null
+ type: string
+ format: binary
'401':
description: Unauthorized.
/shared/appointments/request:
@@ -818,7 +880,7 @@ paths:
put:
operationId: modifySectionCell
summary: Modify data in a Lean Canvas section cell
- description: Updates the content of an existing Lean Canvas section cell specified by `sectionCellId`. The server updates the `modificationDate`.
+ description: Updates the content of an existing Lean Canvas section cell specified by `sectionCellId`. The server "updates" (it keeps a record of the previous version to keep a history of all the sectionCells and creates a new ones with the specified modifications) the `modificationDate`.
tags:
- Entrepreneurs API
security:
@@ -834,7 +896,7 @@ paths:
example: 508
requestBody:
required: true
- description: Updated section cell details. `idSectionCell` should match the path parameter. `modificationDate` will be updated by the server.
+ description: Updated section cell details. `sectionCellId` "the path parameter" is the only id that's consideredn the `sectionCellId` id in the request body is ignored. `modificationDate` should be updated by the server.
content:
application/json:
schema:
diff --git a/documentation/openapi/src/entrepreneurApi.yaml b/documentation/openapi/src/entrepreneurApi.yaml
index 3c67c19..6a87345 100644
--- a/documentation/openapi/src/entrepreneurApi.yaml
+++ b/documentation/openapi/src/entrepreneurApi.yaml
@@ -57,7 +57,7 @@ paths:
put:
operationId: modifySectionCell
summary: Modify data in a Lean Canvas section cell
- description: Updates the content of an existing Lean Canvas section cell specified by `sectionCellId`. The server updates the `modificationDate`.
+ description: Updates the content of an existing Lean Canvas section cell specified by `sectionCellId`. The server "updates" (it keeps a record of the previous version to keep a history of all the sectionCells and creates a new ones with the specified modifications) the `modificationDate`.
tags:
- Entrepreneurs API
security:
@@ -72,7 +72,7 @@ paths:
example: 508
requestBody:
required: true
- description: Updated section cell details. `idSectionCell` should match the path parameter. `modificationDate` will be updated by the server.
+ description: Updated section cell details. `sectionCellId` "the path parameter" is the only id that's consideredn the `sectionCellId` id in the request body is ignored. `modificationDate` should be updated by the server.
content:
application/json:
schema:
diff --git a/documentation/openapi/src/main.yaml b/documentation/openapi/src/main.yaml
index 6538d4e..6764669 100644
--- a/documentation/openapi/src/main.yaml
+++ b/documentation/openapi/src/main.yaml
@@ -34,6 +34,8 @@ components:
$ref: "models.yaml#/joinRequest"
projectDecision:
$ref: "models.yaml#/projectDecision"
+ joinRequestDecision:
+ $ref: "models.yaml#/joinRequestDecision"
securitySchemes:
MyINPulse:
@@ -48,7 +50,7 @@ components:
servers:
- url: '{serverProtocol}://{serverHost}:{serverPort}'
- description: API Server Environment
+ description: API Server
variables:
serverProtocol:
enum: [http, https]
@@ -88,6 +90,10 @@ paths:
$ref: "./adminApi.yaml#/paths/~1admin~1pending-accounts"
/admin/accounts/validate/{userId}:
$ref: "./adminApi.yaml#/paths/~1admin~1accounts~1validate~1{userId}"
+ /admin/request-join:
+ $ref: "./adminApi.yaml#/paths/~1admin~1request-join"
+ /admin/request-join/decision/{joinRequestId}:
+ $ref: "./adminApi.yaml#/paths/~1admin~1request-join~1decision~1{joinRequestId}"
/admin/projects:
$ref: "./adminApi.yaml#/paths/~1admin~1projects"
/admin/projects/pending:
diff --git a/documentation/openapi/src/models.yaml b/documentation/openapi/src/models.yaml
index 8a8f578..add0731 100644
--- a/documentation/openapi/src/models.yaml
+++ b/documentation/openapi/src/models.yaml
@@ -91,7 +91,7 @@ sectionCell:
format: date # Using Java LocalDate -> YYYY-MM-DD
description: The date when this cell was last modified.
#readOnly: true # Typically updated by the server on modification
- example: "2025-04-15"
+ example: "yyyy-MM-dd HH:mm"
project:
type: object
@@ -111,7 +111,7 @@ project:
format: date # Using Java LocalDate -> YYYY-MM-DD
description: The date when the project was created in the system.
#readOnly: true # Set by server
- example: "2024-11-20"
+ example: "yyyy-MM-dd HH:mm"
logo:
type: string
format: byte
@@ -124,6 +124,18 @@ project:
incoming to the server should be ignored as the client shouldn't be specifying them.
example: "NaN"
+joinRequest:
+ type: object
+ description: Represents a request from an entrepreneur to join an already existing project.
+ properties:
+ idProject:
+ type: integer
+ description: the ID of the project the entrepreneur wants to join.
+ example: 42
+ entrepreneur:
+ $ref: "#/user-entrepreneur"
+
+
report:
type: object
description: Represents a report associated with an appointment.
@@ -171,17 +183,6 @@ appointment: # Corrected typo
example: "Q3 Roadmap Planning"
# Consider adding project ID or user IDs if relevant association exists
-joinRequest:
- type: object
- description: Represents a request from an entrepreneur to join an existing project.
- properties:
- projectId:
- type: integer
- description: The ID of the project the entrepreneur wants to join.
- example: 12
- # Consider adding userId if the requester isn't implicit from auth context
- # Consider adding a message field
-
projectDecision:
type: object
description: Represents a decision from an admin to accept a pending project.
@@ -194,6 +195,15 @@ projectDecision:
type: integer
description: The ID of the project the admin who will supervise the project in case of admission.
example: 2
+ isAccepted:
+ type: boolean
+ description: The boolean value of the decision.
+ example: "true"
+
+joinRequestDecision:
+ type: object
+ description: Represents a decision from an admin to accept a pending project join request.
+ properties:
isAccepted:
type: boolean
description: The boolean value of the decision.
diff --git a/documentation/openapi/src/sharedApi.yaml b/documentation/openapi/src/sharedApi.yaml
index f142890..cad9af0 100644
--- a/documentation/openapi/src/sharedApi.yaml
+++ b/documentation/openapi/src/sharedApi.yaml
@@ -46,7 +46,7 @@ paths:
name: date
required: true
schema: { type: string, format: date } # Expect YYYY-MM-DD
- description: The modification date to filter by (YYYY-MM-DD).
+ description: The modification date to filter by (YYYY-MM-DD HH:mm).
responses:
"200":
description: OK - List of section cells matching the criteria.
@@ -95,8 +95,8 @@ paths:
/shared/projects/admin/{projectId}: # Path updated
get:
- operationId: getProjectAdmins
- summary: Get admins associated with a project
+ operationId: getProjectAdmin
+ summary: Get admin associated with a project
tags:
- Shared API
security:
@@ -110,7 +110,7 @@ paths:
description: ID of the project.
responses:
"200":
- description: OK - List of admins.
+ description: OK - admin.
content:
application/json:
schema:
@@ -168,11 +168,13 @@ paths:
description: ID of the appointment.
responses:
"200":
- description: OK - Report content returned.
+ description: OK - Report PDF returned.
content:
- application/json:
+ application/pdf:
schema:
- $ref: "./main.yaml#/components/schemas/report"
+ schema:
+ type: string
+ format: binary
"401":
description: Unauthorized.