docs: Improve Swagger JSDoc

2025-12-19 09:13:20 +03:00 · 2025-09-12 12:17:01 +02:00
parent 494800d131
commit b4979d214f
129 changed files with 294 additions and 248 deletions
--- a/client/src/api/activities.js
+++ b/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,
-  getActivitiesInCard,
+  getBoardActivities,
+  getCardActivities,
  makeHandleActivityCreate,
 };
--- a/client/src/api/custom-field-groups.js
+++ b/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,
-  createCustomFieldGroupInCard,
+  createBoardCustomFieldGroup,
+  createCardCustomFieldGroup,
  getCustomFieldGroup,
  updateCustomFieldGroup,
  deleteCustomFieldGroup,
--- a/client/src/api/notification-services.js
+++ b/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,
-  createNotificationServiceInBoard,
+  createUserNotificationService,
+  createBoardNotificationService,
  updateNotificationService,
  testNotificationService,
  deleteNotificationService,
--- a/client/src/sagas/core/services/activities.js
+++ b/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) {
--- a/client/src/sagas/core/services/custom-field-groups.js
+++ b/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,
    ));
--- a/client/src/sagas/core/services/notification-services.js
+++ b/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,
    ));
--- a/server/api/controllers/access-tokens/accept-terms.js
+++ b/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');
--- a/server/api/controllers/access-tokens/create.js
+++ b/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');
--- a/server/api/controllers/access-tokens/delete.js
+++ b/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
--- a/server/api/controllers/access-tokens/exchange-with-oidc.js
+++ b/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');
--- a/server/api/controllers/access-tokens/revoke-pending-token.js
+++ b/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 = {
--- a/server/api/controllers/actions/index-in-board.js
+++ b/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
--- a/server/api/controllers/actions/index-in-card.js
+++ b/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
--- a/server/api/controllers/attachments/create.js
+++ b/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
- *         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
+ *                 example: Important Attachment
 *               requestId:
 *                 type: string
 *                 maxLength: 128
--- a/server/api/controllers/attachments/delete.js
+++ b/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
--- a/server/api/controllers/attachments/update.js
+++ b/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
--- a/server/api/controllers/background-images/create.js
+++ b/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
--- a/server/api/controllers/background-images/delete.js
+++ b/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
--- a/server/api/controllers/base-custom-field-groups/create.js
+++ b/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
--- a/server/api/controllers/base-custom-field-groups/delete.js
+++ b/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
--- a/server/api/controllers/base-custom-field-groups/update.js
+++ b/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
--- a/server/api/controllers/board-memberships/create.js
+++ b/server/api/controllers/board-memberships/create.js
@@ -7,15 +7,16 @@
 * @swagger
 * /boards/{boardId}/memberships:
 *   post:
- *     summary: Add user to board
- *     description: Adds a user to a board. Requires project manager permissions.
+ *     summary: Create board membership
+ *     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:
--- a/server/api/controllers/board-memberships/delete.js
+++ b/server/api/controllers/board-memberships/delete.js
@@ -7,21 +7,22 @@
 * @swagger
 * /board-memberships/{id}:
 *   delete:
- *     summary: Remove user from board
- *     description: Removes a user from a board. Users can remove themselves, or project managers can remove any user.
+ *     summary: Delete board membership
+ *     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:
--- a/server/api/controllers/board-memberships/update.js
+++ b/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
--- a/server/api/controllers/boards/create.js
+++ b/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]
--- a/server/api/controllers/boards/delete.js
+++ b/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
--- a/server/api/controllers/boards/show.js
+++ b/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
--- a/server/api/controllers/boards/update.js
+++ b/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
--- a/server/api/controllers/card-labels/create.js
+++ b/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
--- a/server/api/controllers/card-labels/delete.js
+++ b/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
--- a/server/api/controllers/card-memberships/create.js
+++ b/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
--- a/server/api/controllers/card-memberships/delete.js
+++ b/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
--- a/server/api/controllers/cards/create.js
+++ b/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
--- a/server/api/controllers/cards/delete.js
+++ b/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
--- a/server/api/controllers/cards/duplicate.js
+++ b/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
--- a/server/api/controllers/cards/index.js
+++ b/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
--- a/server/api/controllers/cards/read-notifications.js
+++ b/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
--- a/server/api/controllers/cards/show.js
+++ b/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
--- a/server/api/controllers/cards/update.js
+++ b/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
--- a/server/api/controllers/comments/create.js
+++ b/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
--- a/server/api/controllers/comments/delete.js
+++ b/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
--- a/server/api/controllers/comments/index.js
+++ b/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
--- a/server/api/controllers/comments/update.js
+++ b/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
--- a/server/api/controllers/config/show.js
+++ b/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 = {
--- a/server/api/controllers/custom-field-groups/create-in-board.js
+++ b/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
--- a/server/api/controllers/custom-field-groups/create-in-card.js
+++ b/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
--- a/server/api/controllers/custom-field-groups/delete.js
+++ b/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
--- a/server/api/controllers/custom-field-groups/show.js
+++ b/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:
--- a/server/api/controllers/custom-field-groups/update.js
+++ b/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
--- a/server/api/controllers/custom-field-values/create-or-update.js
+++ b/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
--- a/server/api/controllers/custom-field-values/delete.js
+++ b/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
--- a/server/api/controllers/custom-fields/create-in-base-custom-field-group.js
+++ b/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
--- a/server/api/controllers/custom-fields/create-in-custom-field-group.js
+++ b/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
--- a/server/api/controllers/custom-fields/delete.js
+++ b/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
--- a/server/api/controllers/custom-fields/update.js
+++ b/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
--- a/server/api/controllers/file-attachments/download-thumbnail.js
+++ b/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 = {
--- a/server/api/controllers/file-attachments/download.js
+++ b/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 = {
--- a/server/api/controllers/labels/create.js
+++ b/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
--- a/server/api/controllers/labels/delete.js
+++ b/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
--- a/server/api/controllers/labels/update.js
+++ b/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
--- a/server/api/controllers/lists/clear.js
+++ b/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
--- a/server/api/controllers/lists/create.js
+++ b/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
--- a/server/api/controllers/lists/delete.js
+++ b/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
--- a/server/api/controllers/lists/move-cards.js
+++ b/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
--- a/server/api/controllers/lists/show.js
+++ b/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
--- a/server/api/controllers/lists/sort.js
+++ b/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
--- a/server/api/controllers/lists/update.js
+++ b/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
--- a/server/api/controllers/notification-services/create-in-board.js
+++ b/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
--- a/server/api/controllers/notification-services/create-in-user.js
+++ b/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
--- a/server/api/controllers/notification-services/delete.js
+++ b/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
--- a/server/api/controllers/notification-services/test.js
+++ b/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
--- a/server/api/controllers/notification-services/update.js
+++ b/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
--- a/server/api/controllers/notifications/index.js
+++ b/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
--- a/server/api/controllers/notifications/read-all.js
+++ b/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
--- a/server/api/controllers/notifications/show.js
+++ b/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
--- a/server/api/controllers/notifications/update.js
+++ b/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
--- a/server/api/controllers/project-managers/create.js
+++ b/server/api/controllers/project-managers/create.js
@@ -7,15 +7,16 @@
 * @swagger
 * /projects/{projectId}/managers:
 *   post:
- *     summary: Add 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.
+ *     summary: Create project manager
+ *     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:
--- a/server/api/controllers/project-managers/delete.js
+++ b/server/api/controllers/project-managers/delete.js
@@ -7,21 +7,22 @@
 * @swagger
 * /project-managers/{id}:
 *   delete:
- *     summary: Remove 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.
+ *     summary: Delete 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:
--- a/server/api/controllers/projects/create.js
+++ b/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:
--- a/server/api/controllers/projects/delete.js
+++ b/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
--- a/server/api/controllers/projects/index.js
+++ b/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
--- a/server/api/controllers/projects/show.js
+++ b/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
--- a/server/api/controllers/projects/update.js
+++ b/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
--- a/server/api/controllers/task-lists/create.js
+++ b/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
--- a/server/api/controllers/task-lists/delete.js
+++ b/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
--- a/server/api/controllers/task-lists/show.js
+++ b/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
--- a/server/api/controllers/task-lists/update.js
+++ b/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
--- a/server/api/controllers/tasks/create.js
+++ b/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
--- a/server/api/controllers/tasks/delete.js
+++ b/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
--- a/server/api/controllers/tasks/update.js
+++ b/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
--- a/server/api/controllers/terms/show.js
+++ b/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 = {
--- a/server/api/controllers/users/create.js
+++ b/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:
--- a/server/api/controllers/users/delete.js
+++ b/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
--- a/server/api/controllers/users/index.js
+++ b/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
--- a/server/api/controllers/users/show.js
+++ b/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
--- a/server/api/controllers/users/update-avatar.js
+++ b/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
--- a/server/api/controllers/users/update-email.js
+++ b/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
--- a/server/api/controllers/users/update-password.js
+++ b/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
--- a/server/api/controllers/users/update-username.js
+++ b/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
--- a/server/api/controllers/users/update.js
+++ b/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
--- a/Show More
+++ b/Show More