// src/swagger/api-docs.js
// Swagger API 문서 정의

/**
 * @swagger
 * /auth/register:
 *   post:
 *     tags: [Auth]
 *     summary: 회원가입
 *     description: 새 계정을 생성합니다.
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required: [email, password, name]
 *             properties:
 *               email:
 *                 type: string
 *                 format: email
 *                 example: user@example.com
 *               password:
 *                 type: string
 *                 minLength: 8
 *                 example: Password123!
 *                 description: 8자 이상, 영문/숫자/특수문자 포함
 *               name:
 *                 type: string
 *                 example: 홍길동
 *     responses:
 *       201:
 *         description: 회원가입 성공
 *       400:
 *         description: 유효성 검사 실패
 *       409:
 *         description: 이미 존재하는 이메일
 */

/**
 * @swagger
 * /auth/login:
 *   post:
 *     tags: [Auth]
 *     summary: 로그인
 *     description: 이메일과 비밀번호로 로그인합니다.
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required: [email, password]
 *             properties:
 *               email:
 *                 type: string
 *                 format: email
 *                 example: admin@admin.com
 *               password:
 *                 type: string
 *                 example: Admin123!
 *     responses:
 *       200:
 *         description: 로그인 성공
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: true
 *                 data:
 *                   type: object
 *                   properties:
 *                     user:
 *                       type: object
 *                     accessToken:
 *                       type: string
 *                       description: JWT 액세스 토큰
 *                     refreshToken:
 *                       type: string
 *                       description: JWT 리프레시 토큰
 *       401:
 *         description: 인증 실패
 */

/**
 * @swagger
 * /chat/completions:
 *   post:
 *     tags: [Chat]
 *     summary: 채팅 완성 (OpenAI 호환)
 *     description: |
 *       AI 모델에 메시지를 보내고 응답을 받습니다.
 *       OpenAI API와 호환되는 형식입니다.
 *       
 *       **인증**: JWT 토큰 또는 API 키 (sk-xxx)
 *     security:
 *       - BearerAuth: []
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/ChatCompletionRequest'
 *           examples:
 *             simple:
 *               summary: 간단한 질문
 *               value:
 *                 model: gemini-2.0-flash
 *                 messages:
 *                   - role: user
 *                     content: 안녕하세요!
 *             with_system:
 *               summary: 시스템 프롬프트 포함
 *               value:
 *                 model: gemini-2.0-flash
 *                 messages:
 *                   - role: system
 *                     content: 당신은 친절한 AI 어시스턴트입니다.
 *                   - role: user
 *                     content: 파이썬으로 Hello World 출력하는 코드 알려줘
 *                 temperature: 0.7
 *                 max_tokens: 1000
 *     responses:
 *       200:
 *         description: 성공
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ChatCompletionResponse'
 *       401:
 *         description: 인증 실패
 *       429:
 *         description: 요청 한도 초과
 */

/**
 * @swagger
 * /models:
 *   get:
 *     tags: [Models]
 *     summary: 모델 목록 조회
 *     description: 사용 가능한 AI 모델 목록을 조회합니다.
 *     security:
 *       - BearerAuth: []
 *     responses:
 *       200:
 *         description: 성공
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 object:
 *                   type: string
 *                   example: list
 *                 data:
 *                   type: array
 *                   items:
 *                     type: object
 *                     properties:
 *                       id:
 *                         type: string
 *                         example: gemini-2.0-flash
 *                       object:
 *                         type: string
 *                         example: model
 *                       owned_by:
 *                         type: string
 *                         example: google
 */

/**
 * @swagger
 * /api-keys:
 *   get:
 *     tags: [API Keys]
 *     summary: API 키 목록 조회
 *     description: 발급받은 API 키 목록을 조회합니다.
 *     security:
 *       - BearerAuth: []
 *     responses:
 *       200:
 *         description: 성공
 *   post:
 *     tags: [API Keys]
 *     summary: API 키 발급
 *     description: 새 API 키를 발급받습니다. 키는 한 번만 표시됩니다.
 *     security:
 *       - BearerAuth: []
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required: [name]
 *             properties:
 *               name:
 *                 type: string
 *                 example: My API Key
 *                 description: API 키 이름
 *     responses:
 *       201:
 *         description: 발급 성공
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                 data:
 *                   type: object
 *                   properties:
 *                     key:
 *                       type: string
 *                       description: 발급된 API 키 (한 번만 표시)
 *                       example: sk-abc123def456...
 */

/**
 * @swagger
 * /api-keys/{id}:
 *   delete:
 *     tags: [API Keys]
 *     summary: API 키 폐기
 *     description: API 키를 폐기합니다.
 *     security:
 *       - BearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *         description: API 키 ID
 *     responses:
 *       200:
 *         description: 폐기 성공
 *       404:
 *         description: API 키를 찾을 수 없음
 */

/**
 * @swagger
 * /usage:
 *   get:
 *     tags: [Usage]
 *     summary: 사용량 요약 조회
 *     description: 오늘/이번 달 사용량 요약을 조회합니다.
 *     security:
 *       - BearerAuth: []
 *     responses:
 *       200:
 *         description: 성공
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                 data:
 *                   type: object
 *                   properties:
 *                     plan:
 *                       type: string
 *                       example: free
 *                     limit:
 *                       type: object
 *                       properties:
 *                         monthly:
 *                           type: integer
 *                         remaining:
 *                           type: integer
 *                     usage:
 *                       type: object
 *                       properties:
 *                         today:
 *                           type: object
 *                         monthly:
 *                           type: object
 */

/**
 * @swagger
 * /usage/logs:
 *   get:
 *     tags: [Usage]
 *     summary: 사용 로그 조회
 *     description: API 호출 로그를 조회합니다.
 *     security:
 *       - BearerAuth: []
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           default: 1
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           default: 20
 *     responses:
 *       200:
 *         description: 성공
 */

/**
 * @swagger
 * /admin/users:
 *   get:
 *     tags: [Admin]
 *     summary: 사용자 목록 조회 (관리자)
 *     description: 모든 사용자 목록을 조회합니다. 관리자 권한 필요.
 *     security:
 *       - BearerAuth: []
 *     responses:
 *       200:
 *         description: 성공
 *       403:
 *         description: 권한 없음
 */

/**
 * @swagger
 * /admin/providers:
 *   get:
 *     tags: [Admin]
 *     summary: LLM 프로바이더 목록 (관리자)
 *     description: LLM 프로바이더 설정을 조회합니다. 관리자 권한 필요.
 *     security:
 *       - BearerAuth: []
 *     responses:
 *       200:
 *         description: 성공
 *       403:
 *         description: 권한 없음
 */

/**
 * @swagger
 * /admin/stats:
 *   get:
 *     tags: [Admin]
 *     summary: 시스템 통계 (관리자)
 *     description: 시스템 전체 통계를 조회합니다. 관리자 권한 필요.
 *     security:
 *       - BearerAuth: []
 *     responses:
 *       200:
 *         description: 성공
 *       403:
 *         description: 권한 없음
 */