From 6cdd54ec7c4ef4128fd5447ff7b3c82f2311acee Mon Sep 17 00:00:00 2001
From: Dongwon Choi <cookie000215@gmail.com>
Date: Sun, 28 Jan 2024 16:03:06 +0000
Subject: [PATCH] Docs: rooms.js

---
 src/routes/docs/rooms.js | 432 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 410 insertions(+), 22 deletions(-)

diff --git a/src/routes/docs/rooms.js b/src/routes/docs/rooms.js
index 56dcda9d..b2f24f72 100644
--- a/src/routes/docs/rooms.js
+++ b/src/routes/docs/rooms.js
@@ -1,3 +1,4 @@
+const { roomsSchema } = require("./roomsSchema");
 const { objectIdPattern, roomsPattern } = require("./utils");
 
 const tag = "rooms";
@@ -99,8 +100,18 @@ roomsDocs[`${apiPrefix}/create`] = {
       500: {
         description: "내부 서버 오류",
         content: {
-          "text/html": {
-            example: "Rooms/create : internal server error",
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                error: {
+                  type: "string",
+                },
+              },
+            },
+            example: {
+              error: "Rooms/create : internal server error",
+            },
           },
         },
       },
@@ -139,16 +150,36 @@ roomsDocs[`${apiPrefix}/publicInfo`] = {
       404: {
         description: "해당 id가 존재하지 않음",
         content: {
-          "text/html": {
-            example: "Rooms/publicInfo : id does not exist",
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                error: {
+                  type: "string",
+                },
+              },
+            },
+            example: {
+              error: "Rooms/publicInfo : id does not exist",
+            },
           },
         },
       },
       500: {
         description: "내부 서버 오류",
         content: {
-          "text/html": {
-            example: "Rooms/publicInfo : internal server error",
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                error: {
+                  type: "string",
+                },
+              },
+            },
+            example: {
+              error: "Rooms/publicInfo : internal server error",
+            },
           },
         },
       },
@@ -186,16 +217,36 @@ roomsDocs[`${apiPrefix}/info`] = {
       404: {
         description: "해당 id가 존재하지 않음",
         content: {
-          "text/html": {
-            example: "Rooms/info : id does not exist",
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                error: {
+                  type: "string",
+                },
+              },
+            },
+            example: {
+              error: "Rooms/info : id does not exist",
+            },
           },
         },
       },
       500: {
         description: "내부 서버 오류",
         content: {
-          "text/html": {
-            example: "Rooms/info : internal server error",
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                error: {
+                  type: "string",
+                },
+              },
+            },
+            example: {
+              error: "Rooms/info : internal server error",
+            },
           },
         },
       },
@@ -206,30 +257,367 @@ roomsDocs[`${apiPrefix}/info`] = {
 roomsDocs[`${apiPrefix}/join`] = {
   post: {
     tags: [tag],
-    summary: "",
-    description: "",
-    requestBody: {},
-    responses: {},
+    summary: "진행 중인 방에 참여",
+    description: `room의 ID를 받아 해당 room의 참가자 목록에 요청을 보낸 사용자를 추가합니다.<br/>
+    하나의 User는 최대 5개의 진행중인 방에 참여할 수 있습니다.<br/>
+    아직 정원이 차지 않은 방과 아직 출발하지 않은 방에만 참여할 수 있습니다.`,
+    requestBody: {
+      content: {
+        "application/json": {
+          schema: {
+            type: "object",
+            properties: {
+              roomId: {
+                type: "string",
+                pattern: objectIdPattern,
+              },
+            },
+          },
+        },
+      },
+    },
+    responses: {
+      200: {
+        description: "방의 세부 정보가 담긴 room Object",
+        content: {
+          "application/json": {
+            schema: {
+              $ref: "#/components/schemas/room",
+            },
+          },
+        },
+      },
+      400: {
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                error: {
+                  type: "string",
+                },
+              },
+            },
+            examples: {
+              "사용자가 참여하는 진행 중 방이 5개 이상": {
+                value: {
+                  error: "Rooms/join : participating in too many rooms",
+                },
+              },
+              "입력한 시간의 방이 이미 출발함": {
+                value: {
+                  error: "Room/join : The room has already departed",
+                },
+              },
+              "방의 인원이 모두 찼음": {
+                value: {
+                  error: "Room/join : The room is already full",
+                },
+              },
+            },
+          },
+        },
+      },
+      404: {
+        description: "해당 id를 가진 방이 존재하지 않음",
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                error: {
+                  type: "string",
+                },
+              },
+            },
+            example: {
+              error: "Rooms/join : no corresponding room",
+            },
+          },
+        },
+      },
+      409: {
+        description: "사용자가 이미 참여중임",
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                error: {
+                  type: "string",
+                },
+              },
+            },
+            example: {
+              error: "Rooms/join : {userID} Already in room",
+            },
+          },
+        },
+      },
+      500: {
+        description: "내부 서버 오류",
+        content: {
+          "text/html": {
+            example: "Rooms/join : internal server error",
+          },
+        },
+      },
+    },
   },
 };
 
 roomsDocs[`${apiPrefix}/abort`] = {
   post: {
     tags: [tag],
-    summary: "",
-    description: "",
-    requestBody: {},
-    responses: {},
+    summary: "참여 중인 방에서 퇴장",
+    description: `room의 ID를 받아 해당 room의 참가자 목록에서 요청을 보낸 사용자를 삭제합니다.<br/>
+    출발했지만 정산이 완료되지 않은 방에서는 나갈 수 없습니다.`,
+    requestBody: {
+      content: {
+        "application/json": {
+          schema: {
+            type: "object",
+            properties: {
+              roomId: {
+                type: "string",
+                pattern: objectIdPattern,
+              },
+            },
+          },
+        },
+      },
+    },
+    responses: {
+      200: {
+        content: {
+          "application/json": {
+            schema: {
+              $ref: "#/components/schemas/room",
+            },
+          },
+        },
+      },
+      400: {
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                error: {
+                  type: "string",
+                },
+              },
+            },
+            examples: {
+              "잘못된 userId를 포함한 요청임": {
+                value: {
+                  error: "Rooms/abort : Bad request",
+                },
+              },
+              "정산이 되지 않은 출발한 방은 나갈 수 없음": {
+                value: {
+                  error:
+                    "Rooms/abort : cannot exit room. Settlement is not done",
+                },
+              },
+            },
+          },
+        },
+      },
+      403: {
+        description: "사용자가 해당 방의 구성원이 아님",
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                error: {
+                  type: "string",
+                },
+              },
+            },
+            example: {
+              error: "Rooms/abort : did not joined the room",
+            },
+          },
+        },
+      },
+      404: {
+        description: "해당 id를 가진 방이 존재하지 않음",
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                error: {
+                  type: "string",
+                },
+              },
+            },
+            example: {
+              error: "Rooms/abort : no corresponding room",
+            },
+          },
+        },
+      },
+      500: {
+        description: "내부 서버 오류",
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                error: {
+                  type: "string",
+                },
+              },
+            },
+            example: {
+              error: "Rooms/abort : internal server error",
+            },
+          },
+        },
+      },
+    },
   },
 };
 
 roomsDocs[`${apiPrefix}/search`] = {
   get: {
     tags: [tag],
-    summary: "",
-    description: "",
-    requestBody: {},
-    responses: {},
+    summary: "방 검색",
+    description: `출발지/도착지/날짜를 받아 조건에 맞는 방을 검색합니다.<br/>
+    조건에 맞는 방이 있을 경우, 방들의 정보를 반환하고 없다면 빈 배열을 반환합니다.`,
+    parameters: [
+      {
+        in: "query",
+        name: "name",
+        schema: {
+          type: "string",
+        },
+        description: `검색할 방의 이름<br/>
+        주어진 경우 해당 텍스트가 방의 이름에 포함된 방들만 반환.<br/>
+        주어지지 않은 경우 임의의 이름을 가지는 방들을 검색.`,
+      },
+      {
+        in: "query",
+        name: "from",
+        schema: {
+          type: "string",
+          pattern: objectIdPattern,
+        },
+        description: `출발지 Document의 ObjectId<br/>
+        주어진 경우 출발지가 일치하는 방들만 반환.<br/>
+        주어지지 않은 경우 임의의 출발지를 가지는 방들을 검색.`,
+      },
+      {
+        in: "query",
+        name: "to",
+        schema: {
+          type: "string",
+          pattern: objectIdPattern,
+        },
+        description: `도착지 Document의 ObjectId<br/>
+        주어진 경우 도착지가 일치하는 방들만 반환.<br/>
+        주어지지 않은 경우 임의의 도착지를 가지는 방들을 검색.`,
+      },
+      {
+        in: "query",
+        name: "time",
+        schema: {
+          type: "string",
+          format: "date-time",
+        },
+        description: `출발 시각<br/>
+        주어진 경우 주어진 시간부터 주어진 시간부터 그 다음에 찾아오는 오전 5시 전에 출발하는 방들만 반환.<br/>
+        주어지지 않은 경우 현재 시각부터 그 다음으로 찾아오는 오전 5시 전까지의 방들을 반환.`,
+      },
+      {
+        in: "query",
+        name: "withTime",
+        schema: {
+          type: "boolean",
+        },
+        description: `검색 옵션에 시간 옵션이 포함되어 있는지 여부.<br/>
+        false이고 검색하는 날짜가 오늘 이후인 경우 검색하는 시간을 0시 0분 0초로 설정함.`,
+      },
+      {
+        in: "query",
+        name: "maxPartLength",
+        schema: {
+          type: "integer",
+        },
+        description: ` 방의 최대 인원 수.<br/>
+        주어진 경우 최대 인원 수가 일치하는 방들만 반환.<br/>
+        주어지지 않은 경우 임의의 최대 인원 수를 가지는 방들을 검색.`,
+      },
+      {
+        in: "query",
+        name: "isHome",
+        schema: {
+          type: "boolean",
+        },
+        description: `홈 페이지 검색인지 여부<br/>
+        true인 경우 검색 날짜 범위를 7일로 설정.<br/>
+        false인 경우 검색 날짜 범위를 14일로 설정.<br/>`,
+      },
+    ],
+    responses: {
+      /* TODO: change to array */
+      200: {
+        content: {
+          "application/json": {
+            schema: {
+              $ref: "#/components/schemas/room",
+            },
+          },
+        },
+      },
+      400: {
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                error: {
+                  type: "string",
+                },
+              },
+            },
+            examples: {
+              "출발지와 도착지가 같음": {
+                value: {
+                  error: "Room/search : Bad request",
+                },
+              },
+              "출발/도착지가 존재하지 않는 장소": {
+                value: {
+                  error: "Room/search : no corresponding locations",
+                },
+              },
+            },
+          },
+        },
+      },
+      500: {
+        description: "내부 서버 오류",
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                error: {
+                  type: "string",
+                },
+              },
+            },
+            example: {
+              error: "Rooms/search : internal server error",
+            },
+          },
+        },
+      },
+    },
   },
 };