feat: Add swagger decorators

packages/server/package.json

@@ -109,6 +109,7 @@
     "rtl-detect": "^1.0.4",
     "socket.io": "^4.7.4",
     "source-map-loader": "^4.0.1",
+    "swagger-ui-express": "^5.0.1",
     "tmp-promise": "^3.0.3",
     "ts-transformer-keys": "^0.4.2",
     "tsyringe": "^4.3.0",

packages/server/src/api/controllers/Attachments/AttachmentsController.ts

@@ -5,7 +5,14 @@ import { body, param } from 'express-validator';
 import BaseController from '@/api/controllers/BaseController';
 import { AttachmentsApplication } from '@/services/Attachments/AttachmentsApplication';
 import { AttachmentUploadPipeline } from '@/services/Attachments/S3UploadPipeline';
+import {
+  ApiOperation,
+  ApiResponse,
+  ApiTags,
+  Route,
+} from '@/decorators/swagger-decorators';
 
+@ApiTags('Attachments')
 @Service()
 export class AttachmentsController extends BaseController {
   @Inject()
@@ -121,6 +128,26 @@ export class AttachmentsController extends BaseController {
    * @param {NextFunction} next
    * @returns {Promise<Response|void>}
    */
+  @ApiResponse({
+    status: 200,
+    description: 'Details of the given attachement',
+    schema: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          name: { type: 'string' },
+          email: { type: 'string' },
+        },
+      },
+    },
+  })
+  @ApiOperation({
+    summary: 'Retrieve a specific details of attachment',
+    description: 'Get all registered users',
+  })
+  @Route('/attachments/:id')
   private async getAttachment(
     req: Request,
     res: Response,

packages/server/src/api/controllers/Items/Items.ts

@@ -8,6 +8,11 @@ import { IItemDTO, ItemAction, AbilitySubject } from '@/interfaces';
 import { DATATYPES_LENGTH } from '@/data/DataTypes';
 import CheckAbilities from '@/api/middleware/CheckPolicies';
 import { ItemsApplication } from '@/services/Items/ItemsApplication';
+import {
+  ApiOperation,
+  ApiResponse,
+  Route,
+} from '@/decorators/swagger-decorators';
 
 @Service()
 export default class ItemsController extends BaseController {
@@ -198,6 +203,22 @@ export default class ItemsController extends BaseController {
    * @param {Request} req
    * @param {Response} res
    */
+  @ApiResponse({
+    status: 200,
+    description: 'Details of the given attachement',
+    schema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' },
+        name: { type: 'string' },
+      },
+    },
+  })
+  @ApiOperation({
+    summary: 'Creates a new item (inventory or service)',
+    description: 'Get all registered users',
+  })
+  @Route('/items')
   private async newItem(req: Request, res: Response, next: NextFunction) {
     const { tenantId } = req;
     const itemDTO: IItemDTO = this.matchedBodyData(req);

packages/server/src/decorators/swagger-decorators.ts

@@ -0,0 +1,63 @@
+export const swaggerDocs = {
+  tags: {},
+  paths: {},
+};
+
+// Decorator to set a tag for a route
+export function ApiTags(tag) {
+  return function (target) {
+    if (!swaggerDocs.tags[tag]) {
+      swaggerDocs.tags[tag] = { name: tag };
+    }
+  };
+}
+
+// Decorator to add an operation for a specific route
+export function ApiOperation(options) {
+  return function (target, propertyKey, descriptor) {
+    const routePath = Reflect.getMetadata('path', target, propertyKey);
+
+    swaggerDocs.paths[routePath] = swaggerDocs.paths[routePath] || {};
+    swaggerDocs.paths[routePath].get = {
+      summary: options.summary,
+      description: options.description || '',
+      responses: options.responses || {
+        200: {
+          description: 'Successful Response',
+        },
+      },
+    };
+
+    
+  };
+}
+
+// Decorator to define the route path
+export function Route(path) {
+  return function (target, propertyKey, descriptor) {
+    Reflect.defineMetadata('path', path, target, propertyKey);
+  };
+}
+
+// Decorator to add a response schema for a specific route
+export function ApiResponse(options) {
+  return function (target, propertyKey, descriptor) {
+    const routePath = Reflect.getMetadata('path', target, propertyKey);
+    
+    if (!swaggerDocs.paths[routePath]) {
+      swaggerDocs.paths[routePath] = { get: {} };
+    }
+
+    swaggerDocs.paths[routePath].get.responses =
+      swaggerDocs.paths[routePath].get.responses || {};
+
+    swaggerDocs.paths[routePath].get.responses[options.status] = {
+      description: options.description || 'No description provided',
+      content: {
+        'application/json': {
+          schema: options.schema || {},
+        },
+      },
+    };
+  };
+}

pnpm-lock.yaml

@@ -302,6 +302,9 @@ importers:
       source-map-loader:
         specifier: ^4.0.1
         version: 4.0.2(webpack@5.91.0)
+      swagger-ui-express:
+        specifier: ^5.0.1
+        version: 5.0.1(express@4.19.2)
       tmp-promise:
         specifier: ^3.0.3
         version: 3.0.3
@@ -24208,6 +24211,20 @@ packages:
       stable: 0.1.8
     dev: false
 
+  /swagger-ui-dist@5.17.14:
+    resolution: {integrity: sha512-CVbSfaLpstV65OnSjbXfVd6Sta3q3F7Cj/yYuvHMp1P90LztOLs6PfUnKEVAeiIVQt9u2SaPwv0LiH/OyMjHRw==}
+    dev: false
+
+  /swagger-ui-express@5.0.1(express@4.19.2):
+    resolution: {integrity: sha512-SrNU3RiBGTLLmFU8GIJdOdanJTl4TOmT27tt3bWWHppqYmAZ6IDuEuBvMU6nZq0zLEe6b/1rACXCgLZqO6ZfrA==}
+    engines: {node: '>= v0.10.32'}
+    peerDependencies:
+      express: '>=4.0.0 || >=5.0.0-beta'
+    dependencies:
+      express: 4.19.2
+      swagger-ui-dist: 5.17.14
+    dev: false
+
   /symbol-observable@1.2.0:
     resolution: {integrity: sha512-e900nM8RRtGhlV36KGEU9k65K3mPb1WV70OdjfxlG2EAuM1noi/E/BaW/uMhL7bPEssK8QV57vN3esixjUvcXQ==}
     engines: {node: '>=0.10.0'}