update
This commit is contained in:
silverpro89
228
SWAGGER_GUIDE.md
Normal file
228
SWAGGER_GUIDE.md
Normal file
@@ -0,0 +1,228 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user