From 17b70e8d5e4c38cba583efabb3f98f63c8449b8a Mon Sep 17 00:00:00 2001
From: Methapon2001 <61303214+Methapon2001@users.noreply.github.com>
Date: Mon, 27 Nov 2023 16:55:52 +0700
Subject: [PATCH] docs: swagger folder and subfolder

---
 .../src/controllers/folderController.ts       | 15 ++++
 .../src/controllers/subFolderController.ts    | 45 ++++++++++-
 Services/server/src/swagger.json              | 81 +++++++++++++++----
 3 files changed, 125 insertions(+), 16 deletions(-)

diff --git a/Services/server/src/controllers/folderController.ts b/Services/server/src/controllers/folderController.ts
index 7fb5f79..b0e5abf 100644
--- a/Services/server/src/controllers/folderController.ts
+++ b/Services/server/src/controllers/folderController.ts
@@ -12,6 +12,7 @@ import {
   Tags,
   Request,
   Response,
+  Example,
 } from "tsoa";
 
 import minioClient from "../minio";
@@ -43,6 +44,20 @@ export class FolderController extends Controller {
     "เกิดข้อผิดพลาด ไม่สามารถแสดงรายการแฟ้มได้ กรุณาลองใหม่ในภายหลัง",
   )
   @SuccessResponse(HttpStatusCode.OK, "สำเร็จ")
+  @Example([
+    {
+      path: "ตู้เอกสาร 1/ลิ้นชัก 1/แฟ้ม 1",
+      name: "แฟ้ม 1",
+      createdAt: "2021-07-20T12:33:13.018Z",
+      createdBy: "admin",
+    },
+    {
+      path: "ตู้เอกสาร 1/ลิ้นชัก 1/แฟ้ม 2",
+      name: "แฟ้ม 2",
+      createdAt: "2022-01-23T16:05:02.114Z",
+      createdBy: "admin",
+    },
+  ])
   public async listFolder(
     @Path() cabinetName: string,
     @Path() drawerName: string,
diff --git a/Services/server/src/controllers/subFolderController.ts b/Services/server/src/controllers/subFolderController.ts
index 59c7900..b748d16 100644
--- a/Services/server/src/controllers/subFolderController.ts
+++ b/Services/server/src/controllers/subFolderController.ts
@@ -12,6 +12,7 @@ import {
   Tags,
   Request,
   Response,
+  Example,
 } from "tsoa";
 
 import minioClient from "../minio";
@@ -31,6 +32,11 @@ if (!DEFAULT_INDEX) throw Error("Default ElasticSearch index must be specified."
 
 @Route("/cabinet/{cabinetName}/drawer/{drawerName}/folder/{folderName}/subfolder")
 export class SubFolderController extends Controller {
+  /**
+   * @example cabinetName "ตู้เอกสาร 1"
+   * @example drawerName "ลิ้นชัก 1"
+   * @example folderName "แฟ้ม 1"
+   */
   @Get("/")
   @Tags("แฟ้มย่อย")
   @Security("bearerAuth")
@@ -39,6 +45,20 @@ export class SubFolderController extends Controller {
     "เกิดข้อผิดพลาด ไม่สามารถแสดงรายการแฟ้มได้ กรุณาลองใหม่ในภายหลัง",
   )
   @SuccessResponse(HttpStatusCode.OK, "สำเร็จ")
+  @Example([
+    {
+      path: "ตู้เอกสาร 1/ลิ้นชัก 1/แฟ้ม 1/แฟ้มย่อย 1",
+      name: "แฟ้มย่อย 1",
+      createdAt: "2021-07-20T12:33:13.018Z",
+      createdBy: "admin",
+    },
+    {
+      path: "ตู้เอกสาร 1/ลิ้นชัก 1/แฟ้ม 1/แฟ้มย่อย 2",
+      name: "แฟ้มย่อย 2",
+      createdAt: "2022-01-23T16:05:02.114Z",
+      createdBy: "admin",
+    },
+  ])
   public async listFolder(
     @Path() cabinetName: string,
     @Path() drawerName: string,
@@ -52,6 +72,11 @@ export class SubFolderController extends Controller {
     return list;
   }
 
+  /**
+   * @example cabinetName "ตู้เอกสาร 1"
+   * @example drawerName "ลิ้นชัก 1"
+   * @example folderName "แฟ้ม 1"
+   */
   @Post("/")
   @Tags("แฟ้มย่อย")
   @Security("bearerAuth", ["admin"])
@@ -83,13 +108,25 @@ export class SubFolderController extends Controller {
     return this.setStatus(HttpStatusCode.CREATED);
   }
 
+  /**
+   * @example cabinetName "ตู้เอกสาร 1"
+   * @example drawerName "ลิ้นชัก 1"
+   * @example folderName "แฟ้ม 1"
+   * @example subFolderName "แฟ้มย่อย 1"
+   */
   @Put("/{subFolderName}")
   @Tags("แฟ้มย่อย")
   @Security("bearerAuth", ["admin"])
   @Response(HttpStatusCode.INTERNAL_SERVER_ERROR, "เกิดข้อผิดพลาดไม่สามารถย้ายไฟล์ได้")
   @SuccessResponse(HttpStatusCode.NO_CONTENT, "สำเร็จ")
   public async editFolder(
-    @Body() body: { name: string },
+    @Body()
+    body: {
+      /**
+       * @example "แฟ้มใหม่"
+       */
+      name: string;
+    },
     @Path() cabinetName: string,
     @Path() drawerName: string,
     @Path() folderName: string,
@@ -143,6 +180,12 @@ export class SubFolderController extends Controller {
     return this.setStatus(HttpStatusCode.NO_CONTENT);
   }
 
+  /**
+   * @example cabinetName "ตู้เอกสาร 1"
+   * @example drawerName "ลิ้นชัก 1"
+   * @example folderName "แฟ้ม 1"
+   * @example subFolderName "แฟ้มย่อย 1"
+   */
   @Delete("/{subFolderName}")
   @Tags("แฟ้มย่อย")
   @Security("bearerAuth", ["admin"])
diff --git a/Services/server/src/swagger.json b/Services/server/src/swagger.json
index 4bcff55..08bfd48 100644
--- a/Services/server/src/swagger.json
+++ b/Services/server/src/swagger.json
@@ -1093,6 +1093,24 @@
 										"$ref": "#/components/schemas/StorageFolder"
 									},
 									"type": "array"
+								},
+								"examples": {
+									"Example 1": {
+										"value": [
+											{
+												"path": "ตู้เอกสาร 1/ลิ้นชัก 1/แฟ้ม 1",
+												"name": "แฟ้ม 1",
+												"createdAt": "2021-07-20T12:33:13.018Z",
+												"createdBy": "admin"
+											},
+											{
+												"path": "ตู้เอกสาร 1/ลิ้นชัก 1/แฟ้ม 2",
+												"name": "แฟ้ม 2",
+												"createdAt": "2022-01-23T16:05:02.114Z",
+												"createdBy": "admin"
+											}
+										]
+									}
 								}
 							}
 						}
@@ -1364,6 +1382,24 @@
 										"$ref": "#/components/schemas/StorageFolder"
 									},
 									"type": "array"
+								},
+								"examples": {
+									"Example 1": {
+										"value": [
+											{
+												"path": "ตู้เอกสาร 1/ลิ้นชัก 1/แฟ้ม 1/แฟ้มย่อย 1",
+												"name": "แฟ้มย่อย 1",
+												"createdAt": "2021-07-20T12:33:13.018Z",
+												"createdBy": "admin"
+											},
+											{
+												"path": "ตู้เอกสาร 1/ลิ้นชัก 1/แฟ้ม 1/แฟ้มย่อย 2",
+												"name": "แฟ้มย่อย 2",
+												"createdAt": "2022-01-23T16:05:02.114Z",
+												"createdBy": "admin"
+											}
+										]
+									}
 								}
 							}
 						}
@@ -1387,7 +1423,8 @@
 						"required": true,
 						"schema": {
 							"type": "string"
-						}
+						},
+						"example": "ตู้เอกสาร 1"
 					},
 					{
 						"in": "path",
@@ -1395,7 +1432,8 @@
 						"required": true,
 						"schema": {
 							"type": "string"
-						}
+						},
+						"example": "ลิ้นชัก 1"
 					},
 					{
 						"in": "path",
@@ -1403,7 +1441,8 @@
 						"required": true,
 						"schema": {
 							"type": "string"
-						}
+						},
+						"example": "แฟ้ม 1"
 					}
 				]
 			},
@@ -1437,7 +1476,8 @@
 						"required": true,
 						"schema": {
 							"type": "string"
-						}
+						},
+						"example": "ตู้เอกสาร 1"
 					},
 					{
 						"in": "path",
@@ -1445,7 +1485,8 @@
 						"required": true,
 						"schema": {
 							"type": "string"
-						}
+						},
+						"example": "ลิ้นชัก 1"
 					},
 					{
 						"in": "path",
@@ -1453,7 +1494,8 @@
 						"required": true,
 						"schema": {
 							"type": "string"
-						}
+						},
+						"example": "แฟ้ม 1"
 					}
 				],
 				"requestBody": {
@@ -1504,7 +1546,8 @@
 						"required": true,
 						"schema": {
 							"type": "string"
-						}
+						},
+						"example": "ตู้เอกสาร 1"
 					},
 					{
 						"in": "path",
@@ -1512,7 +1555,8 @@
 						"required": true,
 						"schema": {
 							"type": "string"
-						}
+						},
+						"example": "ลิ้นชัก 1"
 					},
 					{
 						"in": "path",
@@ -1520,7 +1564,8 @@
 						"required": true,
 						"schema": {
 							"type": "string"
-						}
+						},
+						"example": "แฟ้ม 1"
 					},
 					{
 						"in": "path",
@@ -1528,7 +1573,8 @@
 						"required": true,
 						"schema": {
 							"type": "string"
-						}
+						},
+						"example": "แฟ้มย่อย 1"
 					}
 				],
 				"requestBody": {
@@ -1538,7 +1584,8 @@
 							"schema": {
 								"properties": {
 									"name": {
-										"type": "string"
+										"type": "string",
+										"example": "แฟ้มใหม่"
 									}
 								},
 								"required": [
@@ -1574,7 +1621,8 @@
 						"required": true,
 						"schema": {
 							"type": "string"
-						}
+						},
+						"example": "ตู้เอกสาร 1"
 					},
 					{
 						"in": "path",
@@ -1582,7 +1630,8 @@
 						"required": true,
 						"schema": {
 							"type": "string"
-						}
+						},
+						"example": "ลิ้นชัก 1"
 					},
 					{
 						"in": "path",
@@ -1590,7 +1639,8 @@
 						"required": true,
 						"schema": {
 							"type": "string"
-						}
+						},
+						"example": "แฟ้ม 1"
 					},
 					{
 						"in": "path",
@@ -1598,7 +1648,8 @@
 						"required": true,
 						"schema": {
 							"type": "string"
-						}
+						},
+						"example": "แฟ้มย่อย 1"
 					}
 				]
 			}