feature: API 명세 초안 작성 (prgrms-fe-devcourse#215)

* init: api-docs 패키지 초기화

* chore: api-docs 패키지 작성

package.json

@@ -3,6 +3,7 @@
   "packageManager": "[email protected]",
   "private": true,
   "scripts": {
+    "api-docs": "yarn workspace api-docs",
     "common": "yarn workspace common",
     "slack": "yarn workspace slack",
     "web": "yarn workspace web",
@@ -20,7 +21,7 @@
     "typescript": "^5.2.2"
   },
   "lint-staged": {
-    "packages/**/*.{cjs,js,jsx,ts,tsx}": [
+    "packages/{slack,web}/*.{cjs,js,jsx,ts,tsx}": [
       "eslint --fix",
       "prettier --write"
     ]

packages/api-docs/.eslintignore

@@ -0,0 +1,2 @@
+node_modules
+dist

packages/api-docs/.eslintrc.json

@@ -0,0 +1,18 @@
+{
+  "env": {
+    "browser": true,
+    "node": true,
+    "es2021": true
+  },
+  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended", "plugin:prettier/recommended"],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "plugins": ["@typescript-eslint"],
+  "rules": {
+    "no-unused-vars": "off",
+    "@typescript-eslint/no-unused-vars": "warn"
+  }
+}

packages/api-docs/README.md

@@ -0,0 +1,10 @@
+# api-docs
+
+## 실행 방법
+
+```sh
+yarn api-docs start
+```
+
+레포지토리의 최상단 경로에서 위 커맨드를 입력하면 Swagger UI를 보여주는 서버가 실행됩니다.
+이후 브라우저로 localhost 5010번 포트에 접속하면 API 명세를 확인할 수 있습니다.

packages/api-docs/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "api-docs",
+  "packageManager": "[email protected]",
+  "scripts": {
+    "build": "tsc && swagger-cli bundle ./src/swagger/index.yaml --outfile dist/swagger.yaml --type yaml",
+    "start": "swagger-cli bundle ./src/swagger/index.yaml --outfile dist/swagger.yaml --type yaml && ts-node src/app.ts"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.4",
+    "@types/swagger-ui-express": "^4.1.6",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "5.2.2"
+  },
+  "dependencies": {
+    "express": "^4.18.2",
+    "swagger-cli": "^4.0.4",
+    "swagger-ui-express": "^5.0.0",
+    "yaml": "^2.3.4"
+  }
+}

packages/api-docs/src/app.ts

@@ -0,0 +1,21 @@
+import express from 'express';
+import swaggerUi from 'swagger-ui-express';
+import YAML from 'yaml';
+import fs from 'fs';
+import path from 'path';
+
+const file = fs.readFileSync(path.join(__dirname, '../dist/swagger.yaml'), 'utf8');
+const swaggerDocument = YAML.parse(file);
+
+const app = express();
+const PORT = 5010;
+
+app.use('/', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
+
+app.get('/hello', (req, res) => {
+  res.send('Hello World!');
+});
+
+app.listen(PORT, () => {
+  console.log(`API-Docs Server is running on http://localhost:${PORT}`);
+});

packages/api-docs/src/swagger/components/parameters.yaml

@@ -0,0 +1,35 @@
+Authorization:
+  name: Authorization
+  in: header
+  description: 액세스 토큰
+  schema:
+    type: string
+    example: Bearer {accessToken}
+  required: true
+
+postId:
+  name: postId
+  in: path
+  description: 머쓱이의 postId
+  schema:
+    type: integer
+    format: int64
+  required: true
+
+commentId:
+  name: commentId
+  in: path
+  required: true
+  description: 편지의 commentId
+  schema:
+    type: integer
+    format: int64
+
+userId:
+  name: userId
+  in: path
+  description: 사용자의 ID
+  schema:
+    type: integer
+    format: int64
+  required: true

packages/api-docs/src/swagger/components/responses.yaml

@@ -0,0 +1,55 @@
+Unauthorized:
+  description: 액세스 토큰이 없거나 만료되었을 때
+  content:
+    application/json:
+      schema:
+        type: object
+        properties:
+          message:
+            type: string
+        required:
+          - message
+      example:
+        message: 로그인이 필요해요.
+
+NotFoundUser:
+  description: 해당 사용자가 없는 경우<br/>요청에 대한 권한이 없는 경우 ex) 타인의 정보 수정
+  content:
+    application/json:
+      schema:
+        type: object
+        properties:
+          message:
+            type: string
+        required:
+          - message
+      example:
+        message: 사용자를 찾을 수 없어요.
+
+NotFoundComment:
+  description: 해당 편지가 없는 경우<br/>해당 머쓱이의 편지를 읽을 권한이 없는 경우 ex) 타인이 생성한 머쓱이
+  content:
+    application/json:
+      schema:
+        type: object
+        properties:
+          message:
+            type: string
+        required:
+          - message
+      example:
+        message: 편지를 찾을 수 없어요.
+
+NotFoundPost:
+  description: 해당 머쓱이가 없는 경우<br/>요청에 대한 권한이 없는 경우 ex) 타인의 머쓱이 수정
+  content:
+    application/json:
+      schema:
+        type: object
+        properties:
+          message:
+            type: string
+        required:
+          - message
+      example:
+        message: 머쓱이를 찾을 수 없어요.

packages/api-docs/src/swagger/components/schemas.yaml

@@ -0,0 +1,90 @@
+User:
+  type: object
+  properties:
+    userId:
+      type: integer
+    username:
+      type: string
+    name:
+      type: string
+    introduce:
+      type: string
+    slackId:
+      type: string
+    slackWorkspace:
+      type: string
+    imageName:
+      type: string
+    postCount:
+      type: integer
+    commentCount:
+      type: integer
+  required:
+    - userId
+    - username
+    - name
+    - introduce
+    - slackId
+    - slackWorkspace
+    - imageName
+    - postCount
+    - commentCount
+
+Post:
+  type: object
+  properties:
+    postId:
+      type: integer
+    title:
+      type: string
+    content:
+      type: string
+    imageName:
+      type: string
+    comments:
+      type: array
+      items:
+        type: object
+        properties:
+          commentId:
+            type: integer
+          positionX:
+            type: integer
+          positionY:
+            type: integer
+          imageName:
+            type: string
+        required:
+          - commentId
+          - positionX
+          - positionY
+          - imageName
+  required:
+    - postId
+    - title
+    - content
+    - imageName
+    - comments
+
+Comment:
+  type: object
+  properties:
+    commentId:
+      type: integer
+    author:
+      type: string
+    content:
+      type: string
+    positionX:
+      type: integer
+    positionY:
+      type: integer
+    imageName:
+      type: string
+  required:
+    - commentId
+    - author
+    - content
+    - positionX
+    - positionY
+    - imageName

packages/api-docs/src/swagger/index.yaml

@@ -0,0 +1,51 @@
+openapi: 3.0.0
+info:
+  version: 1.0.0
+  title: Swagger Playground
+  description: For Swagger Studying
+  license:
+    name: bbearcookie
+servers:
+  - url: http://localhost:5010/
+
+components:
+  parameters:
+    $ref: './components/parameters.yaml'
+  responses:
+    $ref: './components/responses.yaml'
+  schemas:
+    $ref: './components/schemas.yaml'
+
+paths:
+  /auth/signup:
+    $ref: './paths/auth/signup.yaml'
+  /auth/signin:
+    $ref: './paths/auth/signin.yaml'
+  /auth/signout:
+    $ref: './paths/auth/signout.yaml'
+  /auth/check:
+    $ref: './paths/auth/check.yaml'
+  /auth/password:
+    $ref: './paths/auth/password.yaml'
+
+  /users:
+    $ref: './paths/users/_.yaml'
+  /users/{userId}:
+    $ref: './paths/users/{userId}/_.yaml'
+  /users/{userId}/photo:
+    $ref: './paths/users/{userId}/photo.yaml'
+  /users/{userId}/slack:
+    $ref: './paths/users/{userId}/slack.yaml'
+
+  /slack/verification:
+    $ref: './paths/slack/verification/_.yaml'
+
+  /posts:
+    $ref: './paths/posts/_.yaml'
+  /posts/{postId}:
+    $ref: './paths/posts/{postId}/_.yaml'
+  /posts/{postId}/comments:
+    $ref: './paths/posts/{postId}/comments.yaml'
+
+  /comments/{commentId}:
+    $ref: './paths/comments/{commentId}/_.yaml'

packages/api-docs/src/swagger/paths/auth/check.yaml

@@ -0,0 +1,28 @@
+get:
+  tags:
+    - 인증 / 인가
+  summary: 로그인 확인
+  description: 로그인이 되어있는지 확인합니다.
+  parameters:
+    - name: Authorization
+      $ref: '../../index.yaml#/components/parameters/Authorization'
+  responses:
+    '200':
+      description: 요청 성공
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              userId:
+                type: integer
+              accessToken:
+                type: string
+            required:
+              - userId
+              - accessToken
+            example:
+              userId: 5
+              accessToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwibm
+    '401':
+      $ref: '../../index.yaml#/components/responses/Unauthorized'