docs: Improve Swagger JSDoc

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 = {