feat: Swagger/OpenAPI 문서화 시스템 구축
- Swagger 패키지 설치 및 설정: * swagger-jsdoc, swagger-ui-express 패키지 추가 * /api-docs 엔드포인트에서 Swagger UI 제공 * /api-docs.json 엔드포인트에서 JSON 스펙 제공 - 포괄적인 Swagger 설정 파일 생성: * config/swagger.js: OpenAPI 3.0 스펙 정의 * 공통 스키마 정의 (User, Worker, Project, Task, DailyWorkReport) * 표준 응답 스키마 (SuccessResponse, ErrorResponse, PaginatedResponse) * JWT Bearer 인증 스키마 설정 - API 문서화 적용: * Authentication API: 로그인 엔드포인트 문서화 * Workers API: 전체 CRUD 작업 문서화 * 상세한 요청/응답 스키마 및 예시 포함 * 에러 코드별 응답 정의 - Swagger UI 커스터마이징: * 브랜딩 및 UI 개선 * 인증 토큰 지속성 설정 * 필터링 및 탐색 기능 활성화 - 접근 방법: * http://localhost:20005/api-docs - Swagger UI * http://localhost:20005/api-docs.json - JSON 스펙
This commit is contained in:
Hyungi Ahn
@@ -1,3 +1,10 @@
|
||||
/**
|
||||
* @swagger
|
||||
* tags:
|
||||
* name: Authentication
|
||||
* description: 사용자 인증 및 권한 관리 API
|
||||
*/
|
||||
|
||||
// routes/authRoutes.js - 비밀번호 변경 및 보안 기능 포함 완전판
|
||||
const express = require('express');
|
||||
const bcrypt = require('bcryptjs');
|
||||
@@ -71,7 +78,49 @@ const recordLoginHistory = async (connection, userId, success, ipAddress, userAg
|
||||
};
|
||||
|
||||
/**
|
||||
* 로그인 - DB 연동 (보안 강화)
|
||||
* @swagger
|
||||
* /api/auth/login:
|
||||
* post:
|
||||
* tags: [Authentication]
|
||||
* summary: 사용자 로그인
|
||||
* description: 사용자명과 비밀번호로 로그인하여 JWT 토큰을 발급받습니다.
|
||||
* requestBody:
|
||||
* required: true
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/LoginRequest'
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 로그인 성공
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/LoginResponse'
|
||||
* 400:
|
||||
* description: 잘못된 요청 (사용자명 또는 비밀번호 누락)
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/ErrorResponse'
|
||||
* 401:
|
||||
* description: 인증 실패 (잘못된 사용자명 또는 비밀번호)
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/ErrorResponse'
|
||||
* 429:
|
||||
* description: 너무 많은 로그인 시도
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/ErrorResponse'
|
||||
* 500:
|
||||
* description: 서버 내부 오류
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/ErrorResponse'
|
||||
*/
|
||||
router.post('/login', authController.login);
|
||||
|
||||
|
||||
@@ -1,20 +1,228 @@
|
||||
/**
|
||||
* @swagger
|
||||
* tags:
|
||||
* name: Workers
|
||||
* description: 작업자 관리 API
|
||||
*/
|
||||
|
||||
const express = require('express');
|
||||
const router = express.Router();
|
||||
const workerController = require('../controllers/workerController');
|
||||
|
||||
// 작업자 생성
|
||||
/**
|
||||
* @swagger
|
||||
* /api/workers:
|
||||
* post:
|
||||
* tags: [Workers]
|
||||
* summary: 작업자 생성
|
||||
* description: 새로운 작업자를 생성합니다.
|
||||
* security:
|
||||
* - bearerAuth: []
|
||||
* requestBody:
|
||||
* required: true
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* required:
|
||||
* - worker_name
|
||||
* properties:
|
||||
* worker_name:
|
||||
* type: string
|
||||
* example: "김철수"
|
||||
* position:
|
||||
* type: string
|
||||
* example: "용접공"
|
||||
* department:
|
||||
* type: string
|
||||
* example: "생산부"
|
||||
* phone:
|
||||
* type: string
|
||||
* example: "010-1234-5678"
|
||||
* email:
|
||||
* type: string
|
||||
* format: email
|
||||
* example: "worker@technicalkorea.com"
|
||||
* responses:
|
||||
* 201:
|
||||
* description: 작업자 생성 성공
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/SuccessResponse'
|
||||
* 400:
|
||||
* description: 잘못된 요청
|
||||
* 401:
|
||||
* description: 인증 필요
|
||||
* 500:
|
||||
* description: 서버 오류
|
||||
* get:
|
||||
* tags: [Workers]
|
||||
* summary: 전체 작업자 조회
|
||||
* description: 모든 작업자 목록을 조회합니다.
|
||||
* security:
|
||||
* - bearerAuth: []
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 작업자 목록 조회 성공
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* success:
|
||||
* type: boolean
|
||||
* example: true
|
||||
* message:
|
||||
* type: string
|
||||
* example: "작업자 목록 조회 성공"
|
||||
* data:
|
||||
* type: array
|
||||
* items:
|
||||
* $ref: '#/components/schemas/Worker'
|
||||
* meta:
|
||||
* type: object
|
||||
* properties:
|
||||
* count:
|
||||
* type: integer
|
||||
* example: 10
|
||||
* 401:
|
||||
* description: 인증 필요
|
||||
* 500:
|
||||
* description: 서버 오류
|
||||
*/
|
||||
router.post('/', workerController.createWorker);
|
||||
|
||||
// 전체 작업자 조회
|
||||
router.get('/', workerController.getAllWorkers);
|
||||
|
||||
// 특정 작업자 조회
|
||||
/**
|
||||
* @swagger
|
||||
* /api/workers/{worker_id}:
|
||||
* get:
|
||||
* tags: [Workers]
|
||||
* summary: 특정 작업자 조회
|
||||
* description: ID로 특정 작업자 정보를 조회합니다.
|
||||
* security:
|
||||
* - bearerAuth: []
|
||||
* parameters:
|
||||
* - in: path
|
||||
* name: worker_id
|
||||
* required: true
|
||||
* schema:
|
||||
* type: integer
|
||||
* description: 작업자 ID
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 작업자 조회 성공
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* success:
|
||||
* type: boolean
|
||||
* example: true
|
||||
* message:
|
||||
* type: string
|
||||
* example: "작업자 조회 성공"
|
||||
* data:
|
||||
* $ref: '#/components/schemas/Worker'
|
||||
* 400:
|
||||
* description: 잘못된 작업자 ID
|
||||
* 401:
|
||||
* description: 인증 필요
|
||||
* 404:
|
||||
* description: 작업자를 찾을 수 없음
|
||||
* 500:
|
||||
* description: 서버 오류
|
||||
* put:
|
||||
* tags: [Workers]
|
||||
* summary: 작업자 정보 수정
|
||||
* description: 작업자 정보를 수정합니다.
|
||||
* security:
|
||||
* - bearerAuth: []
|
||||
* parameters:
|
||||
* - in: path
|
||||
* name: worker_id
|
||||
* required: true
|
||||
* schema:
|
||||
* type: integer
|
||||
* description: 작업자 ID
|
||||
* requestBody:
|
||||
* required: true
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* worker_name:
|
||||
* type: string
|
||||
* example: "김철수"
|
||||
* position:
|
||||
* type: string
|
||||
* example: "용접공"
|
||||
* department:
|
||||
* type: string
|
||||
* example: "생산부"
|
||||
* phone:
|
||||
* type: string
|
||||
* example: "010-1234-5678"
|
||||
* email:
|
||||
* type: string
|
||||
* format: email
|
||||
* example: "worker@technicalkorea.com"
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 작업자 수정 성공
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/SuccessResponse'
|
||||
* 400:
|
||||
* description: 잘못된 요청
|
||||
* 401:
|
||||
* description: 인증 필요
|
||||
* 404:
|
||||
* description: 작업자를 찾을 수 없음
|
||||
* 500:
|
||||
* description: 서버 오류
|
||||
* delete:
|
||||
* tags: [Workers]
|
||||
* summary: 작업자 삭제
|
||||
* description: 작업자를 삭제합니다.
|
||||
* security:
|
||||
* - bearerAuth: []
|
||||
* parameters:
|
||||
* - in: path
|
||||
* name: worker_id
|
||||
* required: true
|
||||
* schema:
|
||||
* type: integer
|
||||
* description: 작업자 ID
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 작업자 삭제 성공
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* success:
|
||||
* type: boolean
|
||||
* example: true
|
||||
* message:
|
||||
* type: string
|
||||
* example: "작업자가 성공적으로 삭제되었습니다."
|
||||
* 400:
|
||||
* description: 잘못된 작업자 ID
|
||||
* 401:
|
||||
* description: 인증 필요
|
||||
* 404:
|
||||
* description: 작업자를 찾을 수 없음
|
||||
* 500:
|
||||
* description: 서버 오류
|
||||
*/
|
||||
router.get('/:worker_id', workerController.getWorkerById);
|
||||
|
||||
// 작업자 업데이트
|
||||
router.put('/:worker_id', workerController.updateWorker);
|
||||
|
||||
// 작업자 삭제
|
||||
router.delete('/:worker_id', workerController.removeWorker);
|
||||
|
||||
module.exports = router;
|
||||
Reference in New Issue
Block a user