229 lines
4.9 KiB
Markdown
229 lines
4.9 KiB
Markdown
# 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
|