docs: Add full Swagger JSDoc coverage

server/api/responses/conflict.js

@@ -31,6 +31,30 @@
  * ```
  */
 
+/**
+ * @swagger
+ * components:
+ *   responses:
+ *     Conflict:
+ *       description: Request conflicts with current state of the resource
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - code
+ *               - message
+ *             properties:
+ *               code:
+ *                 type: string
+ *                 description: Error code
+ *                 example: E_CONFLICT
+ *               message:
+ *                 type: string
+ *                 description: Error message
+ *                 example: Resource already exists
+ */
+
 module.exports = function conflict(message) {
   const { res } = this;
 

server/api/responses/forbidden.js

@@ -31,6 +31,30 @@
  * ```
  */
 
+/**
+ * @swagger
+ * components:
+ *   responses:
+ *     Forbidden:
+ *       description: Access forbidden - insufficient permissions
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - code
+ *               - message
+ *             properties:
+ *               code:
+ *                 type: string
+ *                 description: Error code
+ *                 example: E_FORBIDDEN
+ *               message:
+ *                 type: string
+ *                 description: Error message
+ *                 example: Not enough rights
+ */
+
 module.exports = function forbidden(message) {
   const { res } = this;
 

server/api/responses/notFound.js

@@ -31,6 +31,30 @@
  * ```
  */
 
+/**
+ * @swagger
+ * components:
+ *   responses:
+ *     NotFound:
+ *       description: Resource not found
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - code
+ *               - message
+ *             properties:
+ *               code:
+ *                 type: string
+ *                 description: Error code
+ *                 example: E_NOT_FOUND
+ *               message:
+ *                 type: string
+ *                 description: Error message
+ *                 example: Resource not found
+ */
+
 module.exports = function notFound(message) {
   const { res } = this;
 

server/api/responses/unauthorized.js

@@ -31,6 +31,30 @@
  * ```
  */
 
+/**
+ * @swagger
+ * components:
+ *   responses:
+ *     Unauthorized:
+ *       description: Authentication required or invalid credentials
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - code
+ *               - message
+ *             properties:
+ *               code:
+ *                 type: string
+ *                 description: Error code
+ *                 example: E_UNAUTHORIZED
+ *               message:
+ *                 type: string
+ *                 description: Error message
+ *                 example: Access token is missing, invalid or expired
+ */
+
 module.exports = function unauthorized(message) {
   const { res } = this;
 

server/api/responses/unprocessableEntity.js

@@ -31,6 +31,30 @@
  * ```
  */
 
+/**
+ * @swagger
+ * components:
+ *   responses:
+ *     UnprocessableEntity:
+ *       description: Request contains semantic errors or validation failures
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - code
+ *               - message
+ *             properties:
+ *               code:
+ *                 type: string
+ *                 description: Error code
+ *                 example: E_UNPROCESSABLE_ENTITY
+ *               message:
+ *                 type: string
+ *                 description: Error message
+ *                 example: Validation failed
+ */
+
 module.exports = function unprocessableEntity(message) {
   const { res } = this;
 

server/api/responses/validationError.js

@@ -0,0 +1,68 @@
+/*!
+ * Copyright (c) 2024 PLANKA Software GmbH
+ * Licensed under the Fair Use License: https://github.com/plankanban/planka/blob/master/LICENSE.md
+ */
+
+/**
+ * validationError.js
+ *
+ * A custom response.
+ *
+ * Example usage:
+ * ```
+ *     return res.validationError();
+ *     // -or-
+ *     return res.validationError(optionalData);
+ * ```
+ *
+ * Or with actions2:
+ * ```
+ *     exits: {
+ *       somethingHappened: {
+ *         responseType: 'validationError'
+ *       }
+ *     }
+ * ```
+ *
+ * ```
+ *     throw 'somethingHappened';
+ *     // -or-
+ *     throw { somethingHappened: optionalData }
+ * ```
+ */
+
+/**
+ * @swagger
+ * components:
+ *   responses:
+ *     ValidationError:
+ *       description: Request validation failed due to missing or invalid parameters
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - code
+ *               - problems
+ *               - message
+ *             properties:
+ *               code:
+ *                 type: string
+ *                 description: Error code
+ *                 example: E_MISSING_OR_INVALID_PARAMS
+ *               problems:
+ *                 type: array
+ *                 description: Array of specific validation error messages
+ *                 items:
+ *                   type: string
+ *                 example: [
+ *                   "\"emailOrUsername\" is required, but it was not defined.",
+ *                   "\"password\" is required, but it was not defined."
+ *                 ]
+ *               message:
+ *                 type: string
+ *                 description: Error message
+ *                 example: The server could not fulfill this request (`POST /api/access-tokens`) due to 2 missing or invalid parameters.
+ */
+
+module.exports = function validationError() {};