From d239003047b410eedbcbae43dc10adf6c9ec96d1 Mon Sep 17 00:00:00 2001
From: Ahmed Bouhuolia <a.bouhuolia@gmail.com>
Date: Sat, 7 Sep 2024 15:17:10 +0200
Subject: [PATCH] feat: Document API endpoints using Swagger

---
 packages/server/package.json                  |  1 +
 .../Attachments/AttachmentsController.ts      | 27 +++++++++++++++++++
 .../server/src/api/controllers/Items/Items.ts | 21 +++++++++++++++
 pnpm-lock.yaml                                | 17 ++++++++++++
 4 files changed, 66 insertions(+)

diff --git a/packages/server/package.json b/packages/server/package.json
index b07d5694b..c110993c4 100644
--- a/packages/server/package.json
+++ b/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",
diff --git a/packages/server/src/api/controllers/Attachments/AttachmentsController.ts b/packages/server/src/api/controllers/Attachments/AttachmentsController.ts
index ad75ef550..8576aaa50 100644
--- a/packages/server/src/api/controllers/Attachments/AttachmentsController.ts
+++ b/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,
diff --git a/packages/server/src/api/controllers/Items/Items.ts b/packages/server/src/api/controllers/Items/Items.ts
index 814358fd2..ad9f25304 100644
--- a/packages/server/src/api/controllers/Items/Items.ts
+++ b/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);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f26282a66..d96720a9b 100644
--- a/pnpm-lock.yaml
+++ b/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'}