docs: Improve Swagger JSDoc

client/src/api/activities.js

@@ -16,13 +16,13 @@ export const transformActivity = (activity) => ({
 
 /* Actions */
 
-const getActivitiesInBoard = (boardId, data, headers) =>
+const getBoardActivities = (boardId, data, headers) =>
   socket.get(`/boards/${boardId}/actions`, data, headers).then((body) => ({
     ...body,
     items: body.items.map(transformActivity),
   }));
 
-const getActivitiesInCard = (cardId, data, headers) =>
+const getCardActivities = (cardId, data, headers) =>
   socket.get(`/cards/${cardId}/actions`, data, headers).then((body) => ({
     ...body,
     items: body.items.map(transformActivity),
@@ -38,7 +38,7 @@ const makeHandleActivityCreate = (next) => (body) => {
 };
 
 export default {
-  getActivitiesInBoard,
+  getBoardActivities,
-  getActivitiesInCard,
+  getCardActivities,
   makeHandleActivityCreate,
 };

client/src/api/custom-field-groups.js

@@ -7,10 +7,10 @@ import socket from './socket';
 
 /* Actions */
 
-const createCustomFieldGroupInBoard = (cardId, data, headers) =>
+const createBoardCustomFieldGroup = (cardId, data, headers) =>
   socket.post(`/boards/${cardId}/custom-field-groups`, data, headers);
 
-const createCustomFieldGroupInCard = (cardId, data, headers) =>
+const createCardCustomFieldGroup = (cardId, data, headers) =>
   socket.post(`/cards/${cardId}/custom-field-groups`, data, headers);
 
 const getCustomFieldGroup = (id, headers) =>
@@ -23,8 +23,8 @@ const deleteCustomFieldGroup = (id, headers) =>
   socket.delete(`/custom-field-groups/${id}`, undefined, headers);
 
 export default {
-  createCustomFieldGroupInBoard,
+  createBoardCustomFieldGroup,
-  createCustomFieldGroupInCard,
+  createCardCustomFieldGroup,
   getCustomFieldGroup,
   updateCustomFieldGroup,
   deleteCustomFieldGroup,

client/src/api/notification-services.js

@@ -7,10 +7,10 @@ import socket from './socket';
 
 /* Actions */
 
-const createNotificationServiceInUser = (userId, data, headers) =>
+const createUserNotificationService = (userId, data, headers) =>
   socket.post(`/users/${userId}/notification-services`, data, headers);
 
-const createNotificationServiceInBoard = (boardId, data, headers) =>
+const createBoardNotificationService = (boardId, data, headers) =>
   socket.post(`/boards/${boardId}/notification-services`, data, headers);
 
 const updateNotificationService = (id, data, headers) =>
@@ -23,8 +23,8 @@ const deleteNotificationService = (id, headers) =>
   socket.delete(`/notification-services/${id}`, undefined, headers);
 
 export default {
-  createNotificationServiceInUser,
+  createUserNotificationService,
-  createNotificationServiceInBoard,
+  createBoardNotificationService,
   updateNotificationService,
   testNotificationService,
   deleteNotificationService,

client/src/sagas/core/services/activities.js

@@ -22,7 +22,7 @@ export function* fetchActivitiesInBoard(boardId) {
     ({
       items: activities,
       included: { users },
-    } = yield call(request, api.getActivitiesInBoard, boardId, {
+    } = yield call(request, api.getBoardActivities, boardId, {
       beforeId: lastActivityId || undefined,
     }));
   } catch (error) {
@@ -51,7 +51,7 @@ export function* fetchActivitiesInCard(cardId) {
     ({
       items: activities,
       included: { users },
-    } = yield call(request, api.getActivitiesInCard, cardId, {
+    } = yield call(request, api.getCardActivities, cardId, {
       beforeId: lastActivityId || undefined,
     }));
   } catch (error) {

client/src/sagas/core/services/custom-field-groups.js

@@ -31,7 +31,7 @@ export function* createCustomFieldGroupInBoard(boardId, data) {
   try {
     ({ item: customFieldGroup } = yield call(
       request,
-      api.createCustomFieldGroupInBoard,
+      api.createBoardCustomFieldGroup,
       boardId,
       nextData,
     ));
@@ -69,7 +69,7 @@ export function* createCustomFieldGroupInCard(cardId, data) {
   try {
     ({ item: customFieldGroup } = yield call(
       request,
-      api.createCustomFieldGroupInCard,
+      api.createCardCustomFieldGroup,
       cardId,
       nextData,
     ));

client/src/sagas/core/services/notification-services.js

@@ -27,7 +27,7 @@ export function* createNotificationServiceInCurrentUser(data) {
   try {
     ({ item: notificationService } = yield call(
       request,
-      api.createNotificationServiceInUser,
+      api.createUserNotificationService,
       currentUserId,
       data,
     ));
@@ -54,7 +54,7 @@ export function* createNotificationServiceInBoard(boardId, data) {
   try {
     ({ item: notificationService } = yield call(
       request,
-      api.createNotificationServiceInBoard,
+      api.createBoardNotificationService,
       boardId,
       data,
     ));

server/api/controllers/access-tokens/accept-terms.js

@@ -11,6 +11,7 @@
  *     description: Accept terms during the authentication flow. Converts the pending token to an access token.
  *     tags:
  *       - Access Tokens
+ *     operationId: acceptTerms
  *     requestBody:
  *       required: true
  *       content:
@@ -87,6 +88,7 @@
  *                     - Admin login required to initialize instance
  *                   description: Specific error message
  *                   example: Invalid signature
+ *     security: []
  */
 
 const { getRemoteAddress } = require('../../../utils/remote-address');

server/api/controllers/access-tokens/create.js

@@ -11,6 +11,7 @@
  *     description: Authenticates a user using email/username and password. Returns an access token for API authentication.
  *     tags:
  *       - Access Tokens
+ *     operationId: createAccessToken
  *     requestBody:
  *       required: true
  *       content:
@@ -101,6 +102,7 @@
  *                     - Admin login required to initialize instance
  *                   description: Specific error message
  *                   example: Use single sign-on
+ *     security: []
  */
 
 const bcrypt = require('bcrypt');

server/api/controllers/access-tokens/delete.js

@@ -11,6 +11,7 @@
  *     description: Logs out the current user by deleting the session and access token. Clears HTTP-only cookies if present.
  *     tags:
  *       - Access Tokens
+ *     operationId: deleteAccessToken
  *     responses:
  *       200:
  *         description: Logout successful

server/api/controllers/access-tokens/exchange-with-oidc.js

@@ -11,6 +11,7 @@
  *     description: Exchanges an OIDC authorization code for an access token. Creates a user if they do not exist.
  *     tags:
  *       - Access Tokens
+ *     operationId: exchangeForAccessTokenWithOidc
  *     requestBody:
  *       required: true
  *       content:
@@ -49,6 +50,12 @@
  *                   type: string
  *                   description: Access token for API authentication
  *                   example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ4...
+ *         headers:
+ *           Set-Cookie:
+ *             description: HTTP-only authentication cookie (if withHttpOnlyToken is true)
+ *             schema:
+ *               type: string
+ *               example: httpOnlyToken=29aa3e38-8d24-4029-9743-9cbcf0a0dd5c; HttpOnly; Secure; SameSite=Strict
  *       400:
  *         $ref: '#/components/responses/ValidationError'
  *       401:
@@ -151,6 +158,7 @@
  *                   type: string
  *                   description: Error message
  *                   example: Invalid OIDC configuration
+ *     security: []
  */
 
 const { getRemoteAddress } = require('../../../utils/remote-address');

server/api/controllers/access-tokens/revoke-pending-token.js

@@ -11,6 +11,7 @@
  *     description: Revokes a pending authentication token and cancels the authentication flow.
  *     tags:
  *       - Access Tokens
+ *     operationId: revokePendingToken
  *     requestBody:
  *       required: true
  *       content:
@@ -42,6 +43,7 @@
  *         $ref: '#/components/responses/ValidationError'
  *       404:
  *         $ref: '#/components/responses/NotFound'
+ *     security: []
  */
 
 const Errors = {

server/api/controllers/actions/index-in-board.js

@@ -11,6 +11,7 @@
  *     description: Retrieves a list of actions (activity history) for a specific board, with pagination support.
  *     tags:
  *       - Actions
+ *     operationId: getBoardActions
  *     parameters:
  *       - name: boardId
  *         in: path

server/api/controllers/actions/index-in-card.js

@@ -11,6 +11,7 @@
  *     description: Retrieves a list of actions (activity history) for a specific card, with pagination support.
  *     tags:
  *       - Actions
+ *     operationId: getCardActions
  *     parameters:
  *       - name: cardId
  *         in: path

server/api/controllers/attachments/create.js

@@ -11,6 +11,7 @@
  *     description: Creates an attachment on a card. Requires board editor permissions.
  *     tags:
  *       - Attachments
+ *     operationId: createAttachment
  *     parameters:
  *       - name: cardId
  *         in: path
@@ -22,21 +23,25 @@
  *     requestBody:
  *       required: true
  *       content:
- *         application/json:
+ *         multipart/form-data:
  *           schema:
  *             type: object
  *             required:
  *               - type
- *               - url
  *               - name
  *             properties:
  *               type:
  *                 type: string
- *                 enum: [link]
+ *                 enum: [file, link]
  *                 description: Type of the attachment
  *                 example: link
+ *               file:
+ *                 type: string
+ *                 format: binary
+ *                 description: File to upload
  *               url:
  *                 type: string
+ *                 format: url
  *                 maxLength: 2048
  *                 description: URL for the link attachment
  *                 example: https://google.com/search?q=planka
@@ -44,29 +49,7 @@
  *                 type: string
  *                 maxLength: 128
  *                 description: Name/title of the attachment
- *                 example: Google Link
+ *                 example: Important Attachment
- *         multipart/form-data:
- *           schema:
- *             type: object
- *             required:
- *               - type
- *               - file
- *               - name
- *             properties:
- *               type:
- *                 type: string
- *                 enum: [file]
- *                 description: Type of the attachment
- *                 example: file
- *               file:
- *                 type: string
- *                 format: binary
- *                 description: File to upload
- *               name:
- *                 type: string
- *                 maxLength: 128
- *                 description: Name/title of the attachment
- *                 example: Important Document
  *               requestId:
  *                 type: string
  *                 maxLength: 128

server/api/controllers/attachments/delete.js

@@ -11,6 +11,7 @@
  *     description: Deletes an attachment. Requires board editor permissions.
  *     tags:
  *       - Attachments
+ *     operationId: deleteAttachment
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/attachments/update.js

@@ -11,6 +11,7 @@
  *     description: Updates an attachment. Requires board editor permissions.
  *     tags:
  *       - Attachments
+ *     operationId: updateAttachment
  *     parameters:
  *       - name: id
  *         in: path
@@ -30,7 +31,7 @@
  *                 type: string
  *                 maxLength: 128
  *                 description: Name/title of the attachment
- *                 example: Google Link
+ *                 example: Important Attachment
  *     responses:
  *       200:
  *         description: Attachment updated successfully

server/api/controllers/background-images/create.js

@@ -11,6 +11,7 @@
  *     description: Uploads a background image for a project. Requires project manager permissions.
  *     tags:
  *       - Background Images
+ *     operationId: createBackgroundImage
  *     parameters:
  *       - name: projectId
  *         in: path

server/api/controllers/background-images/delete.js

@@ -11,6 +11,7 @@
  *     description: Deletes a background image. Requires project manager permissions.
  *     tags:
  *       - Background Images
+ *     operationId: deleteBackgroundImage
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/base-custom-field-groups/create.js

@@ -11,6 +11,7 @@
  *     description: Creates a base custom field group within a project. Requires project manager permissions.
  *     tags:
  *       - Base Custom Field Groups
+ *     operationId: createBaseCustomFieldGroup
  *     parameters:
  *       - name: projectId
  *         in: path

server/api/controllers/base-custom-field-groups/delete.js

@@ -11,6 +11,7 @@
  *     description: Deletes a base custom field group. Requires project manager permissions.
  *     tags:
  *       - Base Custom Field Groups
+ *     operationId: deleteBaseCustomFieldGroup
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/base-custom-field-groups/update.js

@@ -11,6 +11,7 @@
  *     description: Updates a base custom field group. Requires project manager permissions.
  *     tags:
  *       - Base Custom Field Groups
+ *     operationId: updateBaseCustomFieldGroup
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/board-memberships/create.js

@@ -7,15 +7,16 @@
  * @swagger
  * /boards/{boardId}/memberships:
  *   post:
- *     summary: Add user to board
+ *     summary: Create board membership
- *     description: Adds a user to a board. Requires project manager permissions.
+ *     description: Creates a board membership within a board. Requires project manager permissions.
  *     tags:
  *       - Board Memberships
+ *     operationId: createBoardMembership
  *     parameters:
  *       - name: boardId
  *         in: path
  *         required: true
- *         description: ID of the board to add the user to
+ *         description: ID of the board to create the board membership in
  *         schema:
  *           type: string
  *           example: "1357158568008091264"
@@ -31,7 +32,7 @@
  *             properties:
  *               userId:
  *                 type: string
- *                 description: ID of the user to add to the board
+ *                 description: ID of the user who is a member of the board
  *                 example: "1357158568008091265"
  *               role:
  *                 type: string
@@ -45,7 +46,7 @@
  *                 example: true
  *     responses:
  *       200:
- *         description: User added to board successfully
+ *         description: Board membership created successfully
  *         content:
  *           application/json:
  *             schema:

server/api/controllers/board-memberships/delete.js

@@ -7,21 +7,22 @@
  * @swagger
  * /board-memberships/{id}:
  *   delete:
- *     summary: Remove user from board
+ *     summary: Delete board membership
- *     description: Removes a user from a board. Users can remove themselves, or project managers can remove any user.
+ *     description: Deletes a board membership. Users can remove their own membership, project managers can remove any membership.
  *     tags:
  *       - Board Memberships
+ *     operationId: deleteBoardMembership
  *     parameters:
  *       - name: id
  *         in: path
  *         required: true
- *         description: ID of the board membership to remove
+ *         description: ID of the board membership to delete
  *         schema:
  *           type: string
  *           example: "1357158568008091264"
  *     responses:
  *       200:
- *         description: User removed from board successfully
+ *         description: Board membership deleted successfully
  *         content:
  *           application/json:
  *             schema:

server/api/controllers/board-memberships/update.js

@@ -11,6 +11,7 @@
  *     description: Updates a board membership. Requires project manager permissions.
  *     tags:
  *       - Board Memberships
+ *     operationId: updateBoardMembership
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/boards/create.js

@@ -11,6 +11,7 @@
  *     description: Creates a board within a project. Supports importing from Trello. Requires project manager permissions.
  *     tags:
  *       - Boards
+ *     operationId: createBoard
  *     parameters:
  *       - name: projectId
  *         in: path
@@ -22,50 +23,6 @@
  *     requestBody:
  *       required: true
  *       content:
- *         application/json:
- *           schema:
- *             type: object
- *             required:
- *               - position
- *               - name
- *             properties:
- *               position:
- *                 type: number
- *                 minimum: 0
- *                 description: Position of the board within the project
- *                 example: 65536
- *               name:
- *                 type: string
- *                 maxLength: 128
- *                 description: Name/title of the board
- *                 example: Development Board
- *               defaultView:
- *                 type: string
- *                 enum: [kanban, grid, list]
- *                 default: kanban
- *                 description: Default view for the board
- *                 example: kanban
- *               defaultCardType:
- *                 type: string
- *                 enum: [project, story]
- *                 default: project
- *                 description: Default card type for new cards
- *                 example: project
- *               limitCardTypesToDefaultOne:
- *                 type: boolean
- *                 default: false
- *                 description: Whether to limit card types to default one
- *                 example: false
- *               alwaysDisplayCardCreator:
- *                 type: boolean
- *                 default: false
- *                 description: Whether to always display the card creator
- *                 example: false
- *               expandTaskListsByDefault:
- *                 type: boolean
- *                 default: false
- *                 description: Whether to expand task lists by default
- *                 example: false
  *         multipart/form-data:
  *           schema:
  *             type: object
@@ -83,33 +40,6 @@
  *                 maxLength: 128
  *                 description: Name/title of the board
  *                 example: Development Board
- *               defaultView:
- *                 type: string
- *                 enum: [kanban, grid, list]
- *                 default: kanban
- *                 description: Default view for the board
- *                 example: kanban
- *               defaultCardType:
- *                 type: string
- *                 enum: [project, story]
- *                 default: project
- *                 description: Default card type for new cards
- *                 example: project
- *               limitCardTypesToDefaultOne:
- *                 type: boolean
- *                 default: false
- *                 description: Whether to limit card types to default one
- *                 example: false
- *               alwaysDisplayCardCreator:
- *                 type: boolean
- *                 default: false
- *                 description: Whether to always display the card creator
- *                 example: false
- *               expandTaskListsByDefault:
- *                 type: boolean
- *                 default: false
- *                 description: Whether to expand task lists by default
- *                 example: false
  *               importType:
  *                 type: string
  *                 enum: [trello]

server/api/controllers/boards/delete.js

@@ -11,6 +11,7 @@
  *     description: Deletes a board and all its contents (lists, cards, etc.). Requires project manager permissions.
  *     tags:
  *       - Boards
+ *     operationId: deleteBoard
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/boards/show.js

@@ -11,6 +11,7 @@
  *     description: Retrieves comprehensive board information, including lists, cards, and other related data.
  *     tags:
  *       - Boards
+ *     operationId: getBoard
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/boards/update.js

@@ -11,6 +11,7 @@
  *     description: Updates a board. Project managers can update all fields, board members can only subscribe/unsubscribe.
  *     tags:
  *       - Boards
+ *     operationId: updateBoard
  *     parameters:
  *       - name: id
  *         in: path
@@ -49,6 +50,7 @@
  *               limitCardTypesToDefaultOne:
  *                 type: boolean
  *                 description: Whether to limit card types to default one
+ *                 example: false
  *               alwaysDisplayCardCreator:
  *                 type: boolean
  *                 description: Whether to limit card types to default one

server/api/controllers/card-labels/create.js

@@ -11,6 +11,7 @@
  *     description: Adds a label to a card. Requires board editor permissions.
  *     tags:
  *       - Card Labels
+ *     operationId: createCardLabel
  *     parameters:
  *       - name: cardId
  *         in: path

server/api/controllers/card-labels/delete.js

@@ -11,6 +11,7 @@
  *     description: Removes a label from a card. Requires board editor permissions.
  *     tags:
  *       - Card Labels
+ *     operationId: deleteCardLabel
  *     parameters:
  *       - name: cardId
  *         in: path

server/api/controllers/card-memberships/create.js

@@ -11,6 +11,7 @@
  *     description: Adds a user to a card. Requires board editor permissions.
  *     tags:
  *       - Card Memberships
+ *     operationId: createCardMembership
  *     parameters:
  *       - name: cardId
  *         in: path

server/api/controllers/card-memberships/delete.js

@@ -11,6 +11,7 @@
  *     description: Removes a user from a card. Requires board editor permissions.
  *     tags:
  *       - Card Memberships
+ *     operationId: deleteCardMembership
  *     parameters:
  *       - name: cardId
  *         in: path

server/api/controllers/cards/create.js

@@ -11,6 +11,7 @@
  *     description: Creates a card within a list. Requires board editor permissions.
  *     tags:
  *       - Cards
+ *     operationId: createCard
  *     parameters:
  *       - name: listId
  *         in: path

server/api/controllers/cards/delete.js

@@ -11,6 +11,7 @@
  *     description: Deletes a card and all its contents (tasks, attachments, etc.). Requires board editor permissions.
  *     tags:
  *       - Cards
+ *     operationId: deleteCard
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/cards/duplicate.js

@@ -11,6 +11,7 @@
  *     description: Creates a duplicate of a card with all its contents (tasks, attachments, etc.). Requires board editor permissions.
  *     tags:
  *       - Cards
+ *     operationId: duplicateCard
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/cards/index.js

@@ -11,6 +11,7 @@
  *     description: Retrieves cards from an endless list with filtering, search, and pagination support.
  *     tags:
  *       - Cards
+ *     operationId: getCards
  *     parameters:
  *       - name: listId
  *         in: path

server/api/controllers/cards/read-notifications.js

@@ -11,6 +11,7 @@
  *     description: Marks all notifications for a specific card as read for the current user. Requires access to the card.
  *     tags:
  *       - Cards
+ *     operationId: readCardNotifications
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/cards/show.js

@@ -11,6 +11,7 @@
  *     description: Retrieves comprehensive card information, including tasks, attachments, and other related data.
  *     tags:
  *       - Cards
+ *     operationId: getCard
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/cards/update.js

@@ -11,6 +11,7 @@
  *     description: Updates a card. Board editors can update all fields, viewers can only subscribe/unsubscribe.
  *     tags:
  *       - Cards
+ *     operationId: updateCard
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/comments/create.js

@@ -11,6 +11,7 @@
  *     description: Creates a new comment on a card. Requires board editor permissions or comment permissions.
  *     tags:
  *       - Comments
+ *     operationId: createComment
  *     parameters:
  *       - name: cardId
  *         in: path

server/api/controllers/comments/delete.js

@@ -11,6 +11,7 @@
  *     description: Deletes a comment. Can be deleted by the comment author (with comment permissions) or project manager.
  *     tags:
  *       - Comments
+ *     operationId: deleteComment
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/comments/index.js

@@ -11,6 +11,7 @@
  *     description: Retrieves comments for a card with pagination support. Requires access to the card.
  *     tags:
  *       - Comments
+ *     operationId: getComments
  *     parameters:
  *       - name: cardId
  *         in: path

server/api/controllers/comments/update.js

@@ -11,6 +11,7 @@
  *     description: Updates a comment. Only the author of the comment can update it.
  *     tags:
  *       - Comments
+ *     operationId: updateComments
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/config/show.js

@@ -11,6 +11,7 @@
  *     description: Retrieves the application configuration.
  *     tags:
  *       - Config
+ *     operationId: getConfig
  *     responses:
  *       200:
  *         description: Configuration retrieved successfully
@@ -23,6 +24,7 @@
  *               properties:
  *                 item:
  *                   $ref: '#/components/schemas/Config'
+ *     security: []
  */
 
 module.exports = {

server/api/controllers/custom-field-groups/create-in-board.js

@@ -7,10 +7,11 @@
  * @swagger
  * /boards/{boardId}/custom-field-groups:
  *   post:
- *     summary: Create custom field group in board
+ *     summary: Create board custom field group
  *     description: Creates a custom field group within a board. Either `baseCustomFieldGroupId` or `name` must be provided. Requires board editor permissions.
  *     tags:
  *       - Custom Field Groups
+ *     operationId: createBoardCustomFieldGroup
  *     parameters:
  *       - name: boardId
  *         in: path

server/api/controllers/custom-field-groups/create-in-card.js

@@ -7,10 +7,11 @@
  * @swagger
  * /cards/{cardId}/custom-field-groups:
  *   post:
- *     summary: Create custom field group in card
+ *     summary: Create card custom field group
  *     description: Creates a custom field group within a card. Either `baseCustomFieldGroupId` or `name` must be provided. Requires board editor permissions.
  *     tags:
  *       - Custom Field Groups
+ *     operationId: createCardCustomFieldGroup
  *     parameters:
  *       - name: cardId
  *         in: path

server/api/controllers/custom-field-groups/delete.js

@@ -11,6 +11,7 @@
  *     description: Deletes a custom field group. Requires board editor permissions.
  *     tags:
  *       - Custom Field Groups
+ *     operationId: deleteCustomFieldGroup
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/custom-field-groups/show.js

@@ -11,6 +11,7 @@
  *     description: Retrieves comprehensive custom field group information, including fields and values. Requires access to the board/card.
  *     tags:
  *       - Custom Field Groups
+ *     operationId: getCustomFieldGroup
  *     parameters:
  *       - name: id
  *         in: path
@@ -40,14 +41,14 @@
  *                   properties:
  *                     customFields:
  *                       type: array
+ *                       description: Related custom fields
  *                       items:
  *                         $ref: '#/components/schemas/CustomField'
- *                       description: Related custom fields
  *                     customFieldValues:
  *                       type: array
+ *                       description: Related custom field values (for card-specific groups)
  *                       items:
  *                         $ref: '#/components/schemas/CustomFieldValue'
- *                       description: Related custom field values (for card-specific groups)
  *       400:
  *         $ref: '#/components/responses/ValidationError'
  *       401:

server/api/controllers/custom-field-groups/update.js

@@ -11,6 +11,7 @@
  *     description: Updates a custom field group. Supports both board-wide and card-specific groups. Requires board editor permissions.
  *     tags:
  *       - Custom Field Groups
+ *     operationId: updateCustomFieldGroup
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/custom-field-values/create-or-update.js

@@ -11,6 +11,7 @@
  *     description: Creates or updates a custom field value for a card. Requires board editor permissions.
  *     tags:
  *       - Custom Field Values
+ *     operationId: updateCustomFieldValue
  *     parameters:
  *       - name: cardId
  *         in: path

server/api/controllers/custom-field-values/delete.js

@@ -11,6 +11,7 @@
  *     description: Deletes a custom field value for a specific card. Requires board editor permissions.
  *     tags:
  *       - Custom Field Values
+ *     operationId: deleteCustomFieldValue
  *     parameters:
  *       - name: cardId
  *         in: path

server/api/controllers/custom-fields/create-in-base-custom-field-group.js

@@ -11,6 +11,7 @@
  *     description: Creates a custom field within a base custom field group. Requires project manager permissions.
  *     tags:
  *       - Custom Fields
+ *     operationId: createCustomFieldInBaseGroup
  *     parameters:
  *       - name: baseCustomFieldGroupId
  *         in: path

server/api/controllers/custom-fields/create-in-custom-field-group.js

@@ -11,6 +11,7 @@
  *     description: Creates a custom field within a custom field group. Requires board editor permissions.
  *     tags:
  *       - Custom Fields
+ *     operationId: createCustomFieldInGroup
  *     parameters:
  *       - name: customFieldGroupId
  *         in: path

server/api/controllers/custom-fields/delete.js

@@ -11,6 +11,7 @@
  *     description: Deletes a custom field. Can delete the in base custom field group (requires project manager permissions) or the custom field group (requires board editor permissions).
  *     tags:
  *       - Custom Fields
+ *     operationId: deleteCustomField
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/custom-fields/update.js

@@ -11,6 +11,7 @@
  *     description: Updates a custom field. Can update in the base custom field group (requires project manager permissions) or the custom field group (requires board editor permissions).
  *     tags:
  *       - Custom Fields
+ *     operationId: updateCustomField
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/file-attachments/download-thumbnail.js

@@ -3,62 +3,6 @@
  * Licensed under the Fair Use License: https://github.com/plankanban/planka/blob/master/LICENSE.md
  */
 
-/**
- * @swagger
- * /attachments/{id}/download/thumbnails/{fileName}.{fileExtension}:
- *   get:
- *     summary: Download file attachment thumbnail
- *     description: Downloads a thumbnail for a file attachment. Only available for image attachments that have thumbnails generated. Requires access to the card.
- *     tags:
- *       - File Attachments
- *     parameters:
- *       - name: id
- *         in: path
- *         required: true
- *         description: ID of the file attachment to download the thumbnail for
- *         schema:
- *           type: string
- *           example: "1357158568008091264"
- *       - name: fileName
- *         in: path
- *         required: true
- *         description: Thumbnail size identifier
- *         schema:
- *           type: string
- *           enum: [outside-360, outside-720]
- *           example: outside-360
- *       - name: fileExtension
- *         in: path
- *         required: true
- *         description: File extension of the thumbnail
- *         schema:
- *           type: string
- *           example: jpg
- *     responses:
- *       200:
- *         description: Thumbnail image returned successfully
- *         content:
- *           image/*:
- *             schema:
- *               type: string
- *               format: binary
- *         headers:
- *           Content-Type:
- *             schema:
- *               type: string
- *             description: MIME type of the thumbnail image
- *           Cache-Control:
- *             schema:
- *               type: string
- *             description: Cache control header
- *       400:
- *         $ref: '#/components/responses/ValidationError'
- *       401:
- *         $ref: '#/components/responses/Unauthorized'
- *       404:
- *         $ref: '#/components/responses/NotFound'
- */
-
 const { idInput } = require('../../../utils/inputs');
 
 const Errors = {

server/api/controllers/file-attachments/download.js

@@ -3,51 +3,6 @@
  * Licensed under the Fair Use License: https://github.com/plankanban/planka/blob/master/LICENSE.md
  */
 
-/**
- * @swagger
- * /attachments/{id}/download:
- *   get:
- *     summary: Download file attachment
- *     description: Downloads a file attachment. Requires access to the card.
- *     tags:
- *       - File Attachments
- *     parameters:
- *       - name: id
- *         in: path
- *         required: true
- *         description: ID of the file attachment to download
- *         schema:
- *           type: string
- *           example: "1357158568008091264"
- *     responses:
- *       200:
- *         description: File attachment content returned successfully
- *         content:
- *           application/octet-stream:
- *             schema:
- *               type: string
- *               format: binary
- *           image/*:
- *             schema:
- *               type: string
- *               format: binary
- *         headers:
- *           Content-Disposition:
- *             schema:
- *               type: string
- *             description: Attachment disposition with filename
- *           Content-Type:
- *             schema:
- *               type: string
- *             description: MIME type of the file
- *       400:
- *         $ref: '#/components/responses/ValidationError'
- *       401:
- *         $ref: '#/components/responses/Unauthorized'
- *       404:
- *         $ref: '#/components/responses/NotFound'
- */
-
 const { idInput } = require('../../../utils/inputs');
 
 const Errors = {

server/api/controllers/labels/create.js

@@ -11,6 +11,7 @@
  *     description: Creates a label within a board. Requires board editor permissions.
  *     tags:
  *       - Labels
+ *     operationId: createLabel
  *     parameters:
  *       - name: boardId
  *         in: path

server/api/controllers/labels/delete.js

@@ -11,6 +11,7 @@
  *     description: Deletes a label. Requires board editor permissions.
  *     tags:
  *       - Labels
+ *     operationId: deleteLabel
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/labels/update.js

@@ -11,6 +11,7 @@
  *     description: Updates a label. Requires board editor permissions.
  *     tags:
  *       - Labels
+ *     operationId: updateLabel
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/lists/clear.js

@@ -11,6 +11,7 @@
  *     description: Deletes all cards from a list. Only works with trash-type lists. Requires project manager or board editor permissions.
  *     tags:
  *       - Lists
+ *     operationId: clearList
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/lists/create.js

@@ -11,6 +11,7 @@
  *     description: Creates a list within a board. Requires board editor permissions.
  *     tags:
  *       - Lists
+ *     operationId: createList
  *     parameters:
  *       - name: boardId
  *         in: path

server/api/controllers/lists/delete.js

@@ -11,6 +11,7 @@
  *     description: Deletes a list and moves its cards to a trash list. Can only delete finite lists. Requires board editor permissions.
  *     tags:
  *       - Lists
+ *     operationId: deleteList
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/lists/move-cards.js

@@ -11,6 +11,7 @@
  *     description: Moves all cards from a closed list to an archive list. Requires board editor permissions.
  *     tags:
  *       - Lists
+ *     operationId: moveListCards
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/lists/show.js

@@ -11,6 +11,7 @@
  *     description: Retrieves comprehensive list information, including cards, attachments, and other related data. Requires access to the board.
  *     tags:
  *       - Lists
+ *     operationId: getList
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/lists/sort.js

@@ -11,6 +11,7 @@
  *     description: Sorts all cards within a list. Requires board editor permissions.
  *     tags:
  *       - Lists
+ *     operationId: sortList
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/lists/update.js

@@ -11,6 +11,7 @@
  *     description: Updates a list. Can move lists between boards. Requires board editor permissions.
  *     tags:
  *       - Lists
+ *     operationId: updateList
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/notification-services/create-in-board.js

@@ -11,6 +11,7 @@
  *     description: Creates a new notification service for a board. Requires project manager permissions.
  *     tags:
  *       - Notification Services
+ *     operationId: createBoardNotificationService
  *     parameters:
  *       - name: boardId
  *         in: path

server/api/controllers/notification-services/create-in-user.js

@@ -11,6 +11,7 @@
  *     description: Creates a new notification service for a user. Users can only create services for themselves.
  *     tags:
  *       - Notification Services
+ *     operationId: createUserNotificationService
  *     parameters:
  *       - name: userId
  *         in: path

server/api/controllers/notification-services/delete.js

@@ -11,6 +11,7 @@
  *     description: Deletes a notification service. Users can delete their own services, project managers can delete board services.
  *     tags:
  *       - Notification Services
+ *     operationId: deleteNotificationService
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/notification-services/test.js

@@ -11,6 +11,7 @@
  *     description: Sends a test notification to verify the notification service is working. Users can test their own services, project managers can test board services.
  *     tags:
  *       - Notification Services
+ *     operationId: testNotificationService
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/notification-services/update.js

@@ -11,6 +11,7 @@
  *     description: Updates a notification service. Users can update their own services, project managers can update board services.
  *     tags:
  *       - Notification Services
+ *     operationId: updateNotificationService
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/notifications/index.js

@@ -11,6 +11,7 @@
  *     description: Retrieves all unread notifications for the current user, including creator users.
  *     tags:
  *       - Notifications
+ *     operationId: getNotifications
  *     responses:
  *       200:
  *         description: Notifications retrieved successfully

server/api/controllers/notifications/read-all.js

@@ -11,6 +11,7 @@
  *     description: Marks all notifications for the current user as read.
  *     tags:
  *       - Notifications
+ *     operationId: readAllNotifications
  *     responses:
  *       200:
  *         description: Notifications marked as read successfully

server/api/controllers/notifications/show.js

@@ -11,6 +11,7 @@
  *     description: Retrieves notification, including creator users. Users can only access their own notifications.
  *     tags:
  *       - Notifications
+ *     operationId: getNotification
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/notifications/update.js

@@ -11,6 +11,7 @@
  *     description: Updates a notification. Users can only update their own notifications.
  *     tags:
  *       - Notifications
+ *     operationId: updateNotification
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/project-managers/create.js

@@ -7,15 +7,16 @@
  * @swagger
  * /projects/{projectId}/managers:
  *   post:
- *     summary: Add project manager
+ *     summary: Create project manager
- *     description: Adds a user as a project manager. Requires admin privileges for shared projects or existing project manager permissions. The user must be an admin or project owner.
+ *     description: Creates a project manager within a project. Requires admin privileges for shared projects or existing project manager permissions. The user must be an admin or project owner.
  *     tags:
  *       - Project Managers
+ *     operationId: createProjectManager
  *     parameters:
  *       - name: projectId
  *         in: path
  *         required: true
- *         description: ID of the project to add the manager to
+ *         description: ID of the project to create the project manager in
  *         schema:
  *           type: string
  *           example: "1357158568008091264"
@@ -34,7 +35,7 @@
  *                 example: "1357158568008091265"
  *     responses:
  *       200:
- *         description: Project manager added successfully
+ *         description: Project manager created successfully
  *         content:
  *           application/json:
  *             schema:

server/api/controllers/project-managers/delete.js

@@ -7,21 +7,22 @@
  * @swagger
  * /project-managers/{id}:
  *   delete:
- *     summary: Remove project manager
+ *     summary: Delete project manager
- *     description: Removes a user from project managers. Requires admin privileges for shared projects or existing project manager permissions. Cannot remove the last project manager.
+ *     description: Deletes a project manager. Requires admin privileges for shared projects or existing project manager permissions. Cannot remove the last project manager.
  *     tags:
  *       - Project Managers
+ *     operationId: deleteProjectManager
  *     parameters:
  *       - name: id
  *         in: path
  *         required: true
- *         description: ID of the project manager to remove
+ *         description: ID of the project manager to delete
  *         schema:
  *           type: string
  *           example: "1357158568008091264"
  *     responses:
  *       200:
- *         description: Project manager removed successfully
+ *         description: Project manager deleted successfully
  *         content:
  *           application/json:
  *             schema:

server/api/controllers/projects/create.js

@@ -11,6 +11,7 @@
  *     description: Creates a project. The current user automatically becomes a project manager.
  *     tags:
  *       - Projects
+ *     operationId: createProject
  *     requestBody:
  *       required: true
  *       content:

server/api/controllers/projects/delete.js

@@ -11,6 +11,7 @@
  *     description: Deletes a project. The project must not have any boards. Requires project manager permissions.
  *     tags:
  *       - Projects
+ *     operationId: deleteProject
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/projects/index.js

@@ -11,6 +11,7 @@
  *     description: Retrieves all projects the current user has access to, including managed projects, membership projects, and shared projects (for admins).
  *     tags:
  *       - Projects
+ *     operationId: getProjects
  *     responses:
  *       200:
  *         description: Projects retrieved successfully

server/api/controllers/projects/show.js

@@ -11,6 +11,7 @@
  *     description: Retrieves comprehensive project information, including boards, board memberships, and other related data.
  *     tags:
  *       - Projects
+ *     operationId: getProject
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/projects/update.js

@@ -11,6 +11,7 @@
  *     description: Updates a project. Accessible fields depend on user permissions.
  *     tags:
  *       - Projects
+ *     operationId: updateProject
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/task-lists/create.js

@@ -11,6 +11,7 @@
  *     description: Creates a task list within a card. Requires board editor permissions.
  *     tags:
  *       - Task Lists
+ *     operationId: createTaskList
  *     parameters:
  *       - name: cardId
  *         in: path

server/api/controllers/task-lists/delete.js

@@ -11,6 +11,7 @@
  *     description: Deletes a task list and all its tasks. Requires board editor permissions.
  *     tags:
  *       - Task Lists
+ *     operationId: deleteTaskList
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/task-lists/show.js

@@ -11,6 +11,7 @@
  *     description: Retrieves task list information, including tasks. Requires access to the card.
  *     tags:
  *       - Task Lists
+ *     operationId: getTaskList
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/task-lists/update.js

@@ -11,6 +11,7 @@
  *     description: Updates a task list. Requires board editor permissions.
  *     tags:
  *       - Task Lists
+ *     operationId: updateTaskList
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/tasks/create.js

@@ -11,6 +11,7 @@
  *     description: Creates a task within a task list. Either `linkedCardId` or `name` must be provided. Requires board editor permissions.
  *     tags:
  *       - Tasks
+ *     operationId: createTask
  *     parameters:
  *       - name: taskListId
  *         in: path

server/api/controllers/tasks/delete.js

@@ -11,6 +11,7 @@
  *     description: Deletes a task. Requires board editor permissions.
  *     tags:
  *       - Tasks
+ *     operationId: deleteTask
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/tasks/update.js

@@ -11,6 +11,7 @@
  *     description: Updates a task. Linked card tasks have limited update options. Requires board editor permissions.
  *     tags:
  *       - Tasks
+ *     operationId: updateTask
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/terms/show.js

@@ -11,6 +11,7 @@
  *     description: Retrieves terms and conditions in the specified language.
  *     tags:
  *       - Terms
+ *     operationId: getTerms
  *     parameters:
  *       - name: type
  *         in: query
@@ -70,6 +71,7 @@
  *         $ref: '#/components/responses/Unauthorized'
  *       404:
  *         $ref: '#/components/responses/NotFound'
+ *     security: []
  */
 
 module.exports = {

server/api/controllers/users/create.js

@@ -11,6 +11,7 @@
  *     description: Creates a user account. Requires admin privileges.
  *     tags:
  *       - Users
+ *     operationId: createUser
  *     requestBody:
  *       required: true
  *       content:

server/api/controllers/users/delete.js

@@ -11,6 +11,7 @@
  *     description: Deletes a user account. Cannot delete the default admin user. Requires admin privileges.
  *     tags:
  *       - Users
+ *     operationId: deleteUser
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/users/index.js

@@ -11,6 +11,7 @@
  *     description: Retrieves a list of all users. Requires admin or project owner privileges.
  *     tags:
  *       - Users
+ *     operationId: getUsers
  *     responses:
  *       200:
  *         description: List of users retrieved successfully

server/api/controllers/users/show.js

@@ -11,6 +11,7 @@
  *     description: Retrieves a user. Use 'me' as ID to get the current user.
  *     tags:
  *       - Users
+ *     operationId: getUser
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/users/update-avatar.js

@@ -11,6 +11,7 @@
  *     description: Updates a user's avatar image. Users can update their own avatar, admins can update any user's avatar.
  *     tags:
  *       - Users
+ *     operationId: updateUserAvatar
  *     parameters:
  *       - name: id
  *         in: path

server/api/controllers/users/update-email.js

@@ -11,6 +11,7 @@
  *     description: Updates a user's email address. Users must provide current password when updating their own email. Admins can update any user's email without a password.
  *     tags:
  *       - Users
+ *     operationId: updateUserEmail
  *     parameters:
  *       - in: path
  *         name: id

server/api/controllers/users/update-password.js

@@ -11,6 +11,7 @@
  *     description: Updates a user's password. Users must provide a current password when updating their own password. Admins can update any user's password without the current password. Returns a new access token when updating own password.
  *     tags:
  *       - Users
+ *     operationId: updateUserPassword
  *     parameters:
  *       - in: path
  *         name: id
@@ -60,7 +61,7 @@
  *                       description: New acces tokens (when updating own password)
  *                       items:
  *                         type: string
- *                       example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ4...
+ *                         example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ4...
  *       400:
  *         $ref: '#/components/responses/ValidationError'
  *       401:

server/api/controllers/users/update-username.js

@@ -11,6 +11,7 @@
  *     description: Updates a user's username. Users must provide a current password when updating their own username (unless they are SSO users with `oidcIgnoreUsername` enabled). Admins can update any user's username without the current password.
  *     tags:
  *       - Users
+ *     operationId: updateUserUsername
  *     parameters:
  *       - in: path
  *         name: id

server/api/controllers/users/update.js

@@ -11,6 +11,7 @@
  *     description: Updates a user. Users can update their own profile, admins can update any user.
  *     tags:
  *       - Users
+ *     operationId: updateUser
  *     parameters:
  *       - name: id
  *         in: path
@@ -40,6 +41,7 @@
  *                 type: object
  *                 nullable: true
  *                 description: Avatar of the user (only null value to remove avatar)
+ *                 example: null
  *               phone:
  *                 type: string
  *                 maxLength: 128