feat: swagger docs & improvement tests (#13)

wizeline · Mar 28, 2024 · 6add2f0 · 6add2f0
1 parent 98dd068
commit 6add2f0
Show file tree

Hide file tree

Showing 31 changed files with 1,142 additions and 253 deletions.
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -68,6 +68,12 @@
       {
         "devDependencies": true
       }
+    ],
+    "jsdoc/check-tag-names": [
+      "warn",
+      {
+        "definedTags": ["swagger"]
+      }
     ]
   },
   "settings": {

diff --git a/.github/workflows/sonar-scan.yml b/.github/workflows/sonar-scan.yml
@@ -0,0 +1,34 @@
+on:
+  # Trigger analysis when pushing to your main branches, and when creating a pull request.
+  push:
+    branches:
+      - main
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+name: Sonnar Scan
+jobs:
+  sonarqube:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '21.7.1' # Adjust to your desired Node.js version
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run tests
+        run: npm test
+
+      - name: SonarQube Scan
+        uses: sonarsource/sonarqube-scan-action@master
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          SONAR_HOST_URL: ${{ secrets.SONAR_HOST }}
diff --git a/.gitignore b/.gitignore
@@ -4,4 +4,6 @@ dist/
 .vscode/
 .env
 out/
-docs/
+docs/
+report.json
+test-report.xml
diff --git a/app/index.js b/app/index.js
@@ -1,5 +1,4 @@
 import App from './server';
-
 /**
  * The port on which the server will listen.
  * @type {number}

diff --git a/app/internal/adapters/routes/auth.routes.js b/app/internal/adapters/routes/auth.routes.js
@@ -11,5 +11,23 @@ import { AuthController } from '../../core/controllers';
 export const AuthRoute = (app) => {
   const router = express.Router();
   app.use('/auth', router);
+
+  /**
+   * @swagger
+   * /auth/token:
+   *   get:
+   *     description: Returns token
+   *     tags:
+   *       - Auth
+   *     responses:
+   *       200:
+   *         description: A token
+   *         content:
+   *         application/json:
+   *          schema:
+   *            $ref: '#/components/schemas/AuthTokenResponse'
+   *       500:
+   *         $ref: '#/components/responses/InternalServerError'
+   */
   router.get('/token', AuthController.getToken);
 };
diff --git a/app/internal/adapters/routes/main.routes.js b/app/internal/adapters/routes/main.routes.js
@@ -11,5 +11,22 @@ import { MainController } from '../../core/controllers';
 export const MainRoute = (app) => {
   const router = express.Router();
   app.use('/', router);
+  /**
+   * @swagger
+   * /health:
+   *   get:
+   *     description: Returns server health
+   *     tags:
+   *       - Main
+   *     responses:
+   *       201:
+   *         description: A User object
+   *         content:
+   *         application/json:
+   *          schema:
+   *            $ref: '#/components/schemas/DefaultResponse'
+   *       500:
+   *         $ref: '#/components/responses/InternalServerError'
+   */
   router.get('/health', MainController.healthCheck);
 };
diff --git a/app/internal/adapters/routes/users.routes.js b/app/internal/adapters/routes/users.routes.js
@@ -2,6 +2,7 @@ import express from 'express';
 import { UsersController } from '../../core/controllers';
 
 /**
+ * {
  * Set up routes related to Users CRUD operations
  * @namespace Users
  * @function UsersRoute
@@ -12,12 +13,120 @@ export const UsersRoute = (app) => {
   const router = express.Router();
   app.use('/users', router);
 
-  // List by id
+  /**
+   * @swagger
+   * /users/{id}:
+   *   get:
+   *     description: Returns a user by id
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         schema:
+   *           type: string
+   *         required: true
+   *         description: ID of the user to get
+   *     security:
+   *       - bearerAuth: []
+   *     tags:
+   *       - Users
+   *     responses:
+   *       200:
+   *         description: User info
+   *         content:
+   *         application/json:
+   *          schema:
+   *            $ref: '#/components/schemas/DefaultResponse'
+   *       401:
+   *         $ref: '#/components/responses/UnauthorizedError'
+   *       500:
+   *         $ref: '#/components/responses/InternalServerError'
+   */
   router.get('/:id', UsersController.getById);
-  // Create a new user
+
+  /**
+   * @swagger
+   * /users:
+   *   post:
+   *     description: Create new user
+   *     requestBody:
+   *       description: User request body
+   *       required: true
+   *       content:
+   *          application/json:
+   *            schema:
+   *              $ref: '#/definitions/User'
+   *     tags:
+   *       - Users
+   *     responses:
+   *       200:
+   *         description: A User response
+   *         content:
+   *         application/json:
+   *          schema:
+   *            $ref: '#/components/schemas/UserResponse'
+   *       401:
+   *         $ref: '#/components/responses/UnauthorizedError'
+   *       500:
+   *         $ref: '#/components/responses/InternalServerError'
+   */
   router.post('/', UsersController.create);
-  // Edit User
+
+  /**
+   * @swagger
+   * /users/{id}:
+   *   put:
+   *     description: Update the user info by id
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         schema:
+   *           type: string
+   *         required: true
+   *         description: ID of the user to update
+   *     requestBody:
+   *       description: User request body
+   *       required: true
+   *       content:
+   *          application/json:
+   *            schema:
+   *              $ref: '#/definitions/User'
+   *     tags:
+   *       - Users
+   *     responses:
+   *       201:
+   *         description: User info
+   *         content:
+   *         application/json:
+   *          schema:
+   *            $ref: '#/components/schemas/DefaultResponse'
+   *       401:
+   *         $ref: '#/components/responses/UnauthorizedError'
+   *       500:
+   *         $ref: '#/components/responses/InternalServerError'
+   */
   router.put('/:id', UsersController.update);
-  // Delete user
+
+  /**
+   * @swagger
+   * /users/{id}:
+   *   delete:
+   *     description: Delete an user by id
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         schema:
+   *           type: string
+   *         required: true
+   *         description: ID of the user to delete
+   *     tags:
+   *       - Users
+   *     responses:
+   *       200:
+   *         $ref: '#/components/responses/Accepted'
+   *       401:
+   *         $ref: '#/components/responses/UnauthorizedError'
+   *       500:
+   *         $ref: '#/components/responses/InternalServerError'
+   */
   router.delete('/:id', UsersController.delete);
 };
diff --git a/app/internal/core/controllers/auth.controller.js b/app/internal/core/controllers/auth.controller.js
@@ -1,13 +1,17 @@
-/** @module Controllers */
+/** @module Controllers/Auth */
 import { constants } from 'http2';
 import { AuthServices } from '../services';
 
+/** @typedef {import('express').Request} Request */
+/** @typedef {import('express').Response} Response */
+/** @typedef {import('express').NextFunction} NextFunction */
+
 /**
  * Callback function getting a token.
  * @function
- * @param {import('express').Request} req - Express request object.
- * @param {import('express').Response} res - Express response object.
- * @param {import('express').NextFunction} next - Express next middleware function.
+ * @param {Request} req - Express request object.
+ * @param {Response} res - Express response object.
+ * @param {NextFunction} next - Express next middleware function.
  */
 const getToken = (req, res, next) => {
   try {
@@ -22,11 +26,6 @@ const getToken = (req, res, next) => {
   }
 };
 
-/**
- * @namespace AuthController
- * @memberof module:Controllers
- * @constant
- */
 export const AuthController = {
   getToken,
 };
diff --git a/app/internal/core/controllers/main.controller.js b/app/internal/core/controllers/main.controller.js
@@ -1,14 +1,18 @@
-/** @module Controllers */
+/** @module Controllers/Main */
 
 import { constants } from 'http2';
 import { MainServices } from '../services';
 
+/** @typedef {import('express').Request} Request */
+/** @typedef {import('express').Response} Response */
+/** @typedef {import('express').NextFunction} NextFunction */
+
 /**
  * Callback function the health check.
  * @function
- * @param {import('express').Request} req - Express request object.
- * @param {import('express').Response} res - Express response object.
- * @param {import('express').NextFunction} next - Express next middleware function.
+ * @param {Request} req - Express request object.
+ * @param {Response} res - Express response object.
+ * @param {NextFunction} next - Express next middleware function.
  */
 const healthCheck = (req, res, next) => {
   try {
@@ -19,10 +23,6 @@ const healthCheck = (req, res, next) => {
   }
 };
 
-/**
- * @namespace MainController
- * @constant
- */
 export const MainController = {
   healthCheck,
 };