feature: API Docs 업데이트 (1월 2일 회의 내용) (#234)

* chore: 스키마 변경 * chore: 머쓱이 목록 조회 수정 * chore: 머쓱이 상세 조회 수정 * chore: 편지 목록 조회, 편지 작성 수정 * chore: 편지 삭제 작성 * chore: 비밀번호 수정 오류 404 -> 500 으로 수정 * chore: 로그인 실패시 validation 제거 * chore: 사용자 정보 수정에 액세스 토큰 추가 * chore: 새로운 API 문서에 따라 orval 생성 * chore: Comment 스키마 변경 * chore: User 스키마에 imageUrl로 수정 * chore: /auth/check에 500 응답으로 수정
prgrms-fe-devcourse · Jan 18, 2024 · 15402a1 · 15402a1
1 parent d557211
commit 15402a1
Show file tree

Hide file tree

Showing 13 changed files with 239 additions and 95 deletions.
diff --git a/packages/api-docs/src/swagger/components/schemas.yaml b/packages/api-docs/src/swagger/components/schemas.yaml
@@ -13,7 +13,7 @@ User:
       type: string
     slackWorkspace:
       type: string
-    imageName:
+    imageUrl:
       type: string
     postCount:
       type: integer
@@ -26,15 +26,47 @@ User:
     - introduce
     - slackId
     - slackWorkspace
-    - imageName
+    - imageUrl
     - postCount
     - commentCount
 
-Post:
+PostList:
+  type: array
+  items:
+    type: object
+    properties:
+      postId:
+        type: integer
+      authorId:
+        type: integer
+      authorName:
+        type: string
+      title:
+        type: string
+      content:
+        type: string
+      imageName:
+        type: string
+      commentCount:
+        type: integer
+    required:
+      - postId
+      - authorId
+      - authorName
+      - title
+      - content
+      - imageName
+      - commentCount
+
+PostDetail:
   type: object
   properties:
     postId:
       type: integer
+    authorId:
+      type: integer
+    authorName:
+      type: string
     title:
       type: string
     content:
@@ -61,6 +93,8 @@ Post:
           - imageName
   required:
     - postId
+    - authorId
+    - authorName
     - title
     - content
     - imageName
@@ -71,7 +105,11 @@ Comment:
   properties:
     commentId:
       type: integer
-    author:
+    postId:
+      type: integer
+    authorId:
+      type: integer
+    nickname:
       type: string
     content:
       type: string
@@ -83,7 +121,8 @@ Comment:
       type: string
   required:
     - commentId
-    - author
+    - postId
+    - nickname
     - content
     - positionX
     - positionY

diff --git a/packages/api-docs/src/swagger/paths/auth/check.yaml b/packages/api-docs/src/swagger/paths/auth/check.yaml
@@ -26,5 +26,16 @@ get:
               accessToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwibm
     '401':
       $ref: '../../index.yaml#/components/responses/Unauthorized'
-    '404':
-      $ref: '../../index.yaml#/components/responses/NotFoundUser'
+    '500':
+      description: 사용자 정보를 찾을 수 없음
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+            required:
+              - message
+          example:
+            message: 사용자를 찾을 수 없어요.
diff --git a/packages/api-docs/src/swagger/paths/auth/password.yaml b/packages/api-docs/src/swagger/paths/auth/password.yaml
@@ -55,5 +55,16 @@ put:
                 password: 비밀번호는 8자 이상이어야 합니다.
     '401':
       $ref: '../../index.yaml#/components/responses/Unauthorized'
-    '404':
-      $ref: '../../index.yaml#/components/responses/NotFoundUser'
+    '500':
+      description: 사용자 정보를 찾을 수 없음
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+            required:
+              - message
+          example:
+            message: 사용자를 찾을 수 없어요.
diff --git a/packages/api-docs/src/swagger/paths/auth/signin.yaml b/packages/api-docs/src/swagger/paths/auth/signin.yaml
@@ -46,17 +46,7 @@ post:
             properties:
               message:
                 type: string
-              validation:
-                type: object
-                properties:
-                  username:
-                    type: string
-                  password:
-                    type: string
             required:
               - message
           example:
-            message: 잘못된 요청이에요.
-            validation:
-              username: 해당 아이디를 가진 사용자가 없어요.
-              password: 비밀번호가 틀렸어요.
+            message: 일치하는 회원이 없어요.
diff --git a/packages/api-docs/src/swagger/paths/comments/{commentId}/_.yaml b/packages/api-docs/src/swagger/paths/comments/{commentId}/_.yaml
@@ -26,3 +26,21 @@ get:
       $ref: '../../../index.yaml#/components/responses/Unauthorized'
     '404':
       $ref: '../../../index.yaml#/components/responses/NotFoundComment'
+
+delete:
+  tags:
+    - 편지
+  summary: 편지 삭제
+  description: 특정 편지를 삭제합니다.
+  parameters:
+    - name: Authorization
+      $ref: '../../../index.yaml#/components/parameters/Authorization'
+    - name: commentId
+      $ref: '../../../index.yaml#/components/parameters/commentId'
+  responses:
+    '200':
+      description: 요청 성공
+    '401':
+      $ref: '../../../index.yaml#/components/responses/Unauthorized'
+    '404':
+      $ref: '../../../index.yaml#/components/responses/NotFoundComment'
diff --git a/packages/api-docs/src/swagger/paths/posts/_.yaml b/packages/api-docs/src/swagger/paths/posts/_.yaml
@@ -35,45 +35,29 @@ get:
       content:
         application/json:
           schema:
-            type: array
-            items:
-              $ref: '../../index.yaml#/components/schemas/Post'
+            $ref: '../../index.yaml#/components/schemas/PostList'
           example:
             - postId: 1
+              authorId: 1
+              authorName: 신짱구
               title: 피드백 머쓱이
               content: 저에게 피드백을 주세요
               imageName: musseuk_default.png
-              comments:
-                - commentId: 1
-                  positionX: 55
-                  positionY: 413
-                  imageName: decoration_beer1.png
-                - commentId: 2
-                  positionX: 23
-                  positionY: 333
-                  imageName: decoration_chicken1.png
+              commentCount: 3
             - postId: 2
+              authorId: 5
+              authorName: 김철수
               title: 잡담 머쓱이
               content: 우하하 잡담용 머쓱이에요
               imageName: musseuk_default.png
-              comments: []
+              commentCount: 0
             - postId: 3
+              authorId: 10
+              authorName: 김영희
               title: 스터디 머쓱이
               content: 스터디를 함께하실 분을 찾습니다
               imageName: musseuk_default.png
-              comments:
-                - commentId: 3
-                  positionX: 55
-                  positionY: 413
-                  imageName: decoration_beer1.png
-                - commentId: 4
-                  positionX: 23
-                  positionY: 333
-                  imageName: decoration_chicken1.png
-                - commentId: 5
-                  positionX: 21
-                  positionY: 111
-                  imageName: decoration_chicken1.png
+              commentCount: 10
 post:
   tags:
     - 머쓱이

diff --git a/packages/api-docs/src/swagger/paths/posts/{postId}/_.yaml b/packages/api-docs/src/swagger/paths/posts/{postId}/_.yaml
@@ -4,8 +4,6 @@ get:
   summary: 머쓱이 상세 조회
   description: 머쓱이의 상세 정보를 조회합니다.
   parameters:
-    - name: Authorization
-      $ref: '../../../index.yaml#/components/parameters/Authorization'
     - name: postId
       $ref: '../../../index.yaml#/components/parameters/postId'
   responses:
@@ -14,9 +12,11 @@ get:
       content:
         application/json:
           schema:
-            $ref: '../../../index.yaml#/components/schemas/Post'
+            $ref: '../../../index.yaml#/components/schemas/PostDetail'
           example:
             postId: 1
+            authorId: 10
+            authorName: 김영희
             title: 피드백 머쓱이
             content: 저에게 피드백을 주세요
             imageName: musseuk_default.png

diff --git a/packages/api-docs/src/swagger/paths/posts/{postId}/comments.yaml b/packages/api-docs/src/swagger/paths/posts/{postId}/comments.yaml
@@ -19,13 +19,17 @@ get:
               $ref: '../../../index.yaml#/components/schemas/Comment'
           example:
             - commentId: 1
-              author: 우주킹왕짱
+              postId: 1
+              authorId: 1
+              nickname: 우주킹왕짱
               content: 당신에게 마음을 전해요
               positionX: 55
               positionY: 413
               imageName: decoration_beer1.png
             - commentId: 2
-              author: 댓글조작단
+              postId: 1
+              authorId: 2
+              nickname: 댓글조작단
               content: 영차 영차
               positionX: 23
               positionY: 333
@@ -43,14 +47,26 @@ post:
   parameters:
     - name: postId
       $ref: '../../../index.yaml#/components/parameters/postId'
+    - name: asSignedUser
+      in: query
+      description: 로그인 된 상태로 요청하는지의 여부<br/>(true로 요청하는 경우 Authorization 헤더에 액세스 토큰을 담아 보내야 함)<br/><br/>true이면 테이블의 authorId에 로그인한 사용자의 ID가 들어감.<br/>false이면 테이블의 authorId에 NULL이 들어감.
+      schema:
+        type: boolean
+        default: false
+    - name: Authorization
+      in: header
+      description: 액세스 토큰 (asSignedUser가 true인 경우에만 해당)
+      schema:
+        type: string
+        example: Bearer {accessToken}
   requestBody:
     required: true
     content:
       application/json:
         schema:
           type: object
           properties:
-            author:
+            nickname:
               type: string
             content:
               type: string
@@ -61,13 +77,13 @@ post:
             imageName:
               type: string
           required:
-            - author
+            - nickname
             - content
             - positionX
             - positionY
             - imageName
         example:
-          author: 우주킹왕짱
+          nickname: 우주킹왕짱
           content: 당신에게 마음을 전해요
           positionX: 55
           positionY: 413
@@ -78,8 +94,26 @@ post:
       content:
         application/json:
           schema:
-            $ref: '../../../index.yaml#/components/schemas/Comment'
+            type: object
+            properties:
+              commentId:
+                type: integer
+            required:
+              - commentId
           example:
             commentId: 7
+    '401':
+      description: 액세스 토큰이 없거나 만료되었을 때 (asSignedUser가 true인 경우에만 해당)
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+            required:
+              - message
+          example:
+            message: 로그인이 필요해요.
     '404':
       $ref: '../../../index.yaml#/components/responses/NotFoundPost'
diff --git a/packages/api-docs/src/swagger/paths/users/_.yaml b/packages/api-docs/src/swagger/paths/users/_.yaml
@@ -32,7 +32,7 @@ get:
               introduce: 안녕하세요 짱구에요
               slackId: U01H9QZJX1T
               slackWorkspace: D9D8A7A7S
-              imageName: 짱구_이미지_링크.png
+              imageUrl: 짱구_이미지_링크.png
               postCount: 3
               commentCount: 5
             - userId: 2
@@ -41,7 +41,7 @@ get:
               introduce: 안녕하세요 철수에요
               slackId: U01H9QZJX2T
               slackWorkspace: D9D8A7A7S
-              imageName: 철수_이미지_링크.png
+              imageUrl: 철수_이미지_링크.png
               postCount: 7
               commentCount: 2
             - userId: 3
@@ -50,6 +50,6 @@ get:
               introduce: 안녕하세요 유리에요
               slackId: U01H9QZJX3T
               slackWorkspace: D9D8A7A7S
-              imageName: 유리_이미지_링크.png
+              imageUrl: 유리_이미지_링크.png
               postCount: 2
               commentCount: 15
diff --git a/packages/api-docs/src/swagger/paths/users/{userId}/_.yaml b/packages/api-docs/src/swagger/paths/users/{userId}/_.yaml
@@ -20,7 +20,7 @@ get:
             introduce: 안녕하세요 짱구에요
             slackId: U01H9QZJX1T
             slackWorkspace: D9D8A7A7S
-            imageName: 짱구_이미지_링크.png
+            imageUrl: 짱구_이미지_링크.png
             postCount: 3
             commentCount: 5
     '404':
@@ -32,6 +32,8 @@ put:
   summary: 사용자의 정보 수정
   description: 사용자의 정보를 수정합니다.
   parameters:
+    - name: Authorization
+      $ref: '../../../index.yaml#/components/parameters/Authorization'
     - name: userId
       in: path
       description: 수정할 사용자의 ID
@@ -68,7 +70,7 @@ put:
             introduce: 저는 짱구에요
             slackId: U01H9QZJX1T
             slackWorkspace: D9D8A7A7S
-            imageName: 짱구_이미지_링크.png
+            imageUrl: 짱구_이미지_링크.png
             postCount: 3
             commentCount: 5
     '400':