# Swagger API Documentation

## 🚀 Truy cập Swagger UI

Sau khi start server, truy cập:

```
http://localhost:3000/api-docs
```

## 📚 Swagger JSON

Lấy định nghĩa OpenAPI 3.0 JSON:

```
http://localhost:3000/api-docs.json
```

## 🔐 Authentication trong Swagger UI

### Bước 1: Login để lấy token

1. Mở endpoint `POST /api/auth/login`
2. Click **"Try it out"**
3. Nhập:
```json
{
  "username": "student001",
  "password": "password123"
}
```
4. Click **"Execute"**
5. Copy `token` từ response

### Bước 2: Authorize

1. Click nút **"Authorize"** 🔓 ở góc trên bên phải
2. Nhập token vào ô **bearerAuth**: `<token_vừa_copy>`
3. Click **"Authorize"**
4. Click **"Close"**

### Bước 3: Test các API cần authentication

Giờ bạn có thể test các endpoint như:
- `GET /api/auth/me`
- `POST /api/auth/logout`
- `POST /api/auth/verify-token`

Token sẽ tự động được thêm vào header `Authorization: Bearer <token>`

---

## 📋 Endpoints đã document

### Authentication APIs

| Method | Endpoint | Description | Auth Required |
|--------|----------|-------------|---------------|
| POST | `/api/auth/login` | Đăng nhập | ❌ |
| POST | `/api/auth/register` | Đăng ký tài khoản | ❌ |
| POST | `/api/auth/verify-token` | Xác thực token | ✅ |
| POST | `/api/auth/logout` | Đăng xuất | ✅ |
| GET | `/api/auth/me` | Lấy thông tin user hiện tại | ✅ |

---

## 🎨 Tính năng Swagger UI

- ✅ **Persist Authorization**: Token được lưu tự động sau khi authorize
- ✅ **Display Request Duration**: Hiển thị thời gian response
- ✅ **Filter**: Tìm kiếm endpoints nhanh
- ✅ **Syntax Highlight**: Code highlighting với theme Monokai
- ✅ **Try it out**: Test API trực tiếp từ UI

---

## 📖 Response Examples

### Login Success Response

```json
{
  "success": true,
  "message": "Đăng nhập thành công",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "username": "student001",
      "email": "student@example.com",
      "profile": {
        "full_name": "Nguyễn Văn A",
        "avatar_url": "https://...",
        "primary_role_info": {
          "role_code": "student",
          "role_name": "Học sinh",
          "school": {
            "id": "uuid",
            "name": "SENA Hà Nội"
          },
          "class": {
            "id": "uuid",
            "name": "K1A"
          }
        }
      },
      "role": {
        "role_id": "uuid",
        "role_code": "student",
        "role_name": "Học sinh",
        "school": { "id": "uuid", "name": "SENA HN" },
        "class": { "id": "uuid", "name": "K1A" }
      },
      "permissions": [
        {
          "code": "view_own_grades",
          "name": "Xem điểm của mình",
          "resource": "grades",
          "action": "view"
        }
      ],
      "last_login": "2026-01-19T10:30:00.000Z",
      "login_count": 15
    }
  }
}
```

### Error Response

```json
{
  "success": false,
  "message": "Username hoặc password không đúng",
  "attemptsLeft": 3
}
```

---

## 🔧 Cấu hình Swagger

File config: `config/swagger.js`

### Thêm endpoint mới

Thêm Swagger JSDoc comment vào controller:

```javascript
/**
 * @swagger
 * /api/your-endpoint:
 *   get:
 *     tags: [YourTag]
 *     summary: Your summary
 *     description: Your description
 *     responses:
 *       200:
 *         description: Success
 */
async yourMethod(req, res) {
  // Your code
}
```

### Thêm schema mới

Trong `config/swagger.js`, thêm vào `components.schemas`:

```javascript
YourSchema: {
  type: 'object',
  properties: {
    id: { type: 'string', format: 'uuid' },
    name: { type: 'string' },
  }
}
```

---

## 🐛 Troubleshooting

### Swagger UI không hiển thị

1. Check server đã start: `npm run dev`
2. Check port 3000 không bị chiếm
3. Check console có error không

### Token không work sau authorize

1. Đảm bảo format: `Bearer <token>` (không có dấu ngoặc)
2. Token phải valid (chưa expire sau 24h)
3. Check response từ login có token không

### CSP errors trong console

Đã được fix trong `app.js` bằng cách thêm:
```javascript
scriptSrc: ["'self'", "'unsafe-inline'"],
imgSrc: ["'self'", "data:", "https:", "validator.swagger.io"]
```

---

## 📝 Best Practices

1. **Luôn test API trong Swagger trước khi code client**
2. **Update documentation khi thêm/sửa endpoint**
3. **Dùng "Try it out" để verify request/response schema**
4. **Copy curl command từ Swagger để debug**
5. **Export Swagger JSON để generate client SDK**

---

## 🎯 Next Steps

Để thêm documentation cho các controller khác:

1. Mở file controller (vd: `controllers/studentController.js`)
2. Thêm Swagger JSDoc comments
3. Restart server
4. Refresh Swagger UI

---

**Last updated:** January 19, 2026  
**Swagger Version:** OpenAPI 3.0.0