358 lines
8.1 KiB
Markdown
358 lines
8.1 KiB
Markdown
# ✅ Swagger Dokümantasyonu Güncellendi!
|
||
|
||
## 📚 Swagger Endpoint'leri
|
||
|
||
**Toplam:** 20 Endpoint, 30+ Method
|
||
|
||
### 🔐 Authentication (7 endpoints)
|
||
|
||
| Method | Endpoint | Açıklama |
|
||
|--------|----------|----------|
|
||
| POST | `/auth/login` | Kullanıcı girişi |
|
||
| POST | `/auth/register` | Yeni kullanıcı kaydı |
|
||
| POST | `/auth/refresh` | Token yenileme |
|
||
| GET | `/auth/me` | Kullanıcı bilgilerini getir |
|
||
| GET | `/auth/verify-email` | Email doğrulama |
|
||
| GET | `/auth/{provider}` | OAuth başlat (Google/GitHub) |
|
||
| GET | `/auth/{provider}/callback` | OAuth callback |
|
||
|
||
---
|
||
|
||
### 👤 User Avatar (2 endpoints)
|
||
|
||
| Method | Endpoint | Açıklama |
|
||
|--------|----------|----------|
|
||
| POST | `/v1/user/avatar` | ✅ Avatar yükle (multipart) |
|
||
| DELETE | `/v1/user/avatar` | ✅ Avatar sil |
|
||
|
||
---
|
||
|
||
### 👨💼 Admin - User Management (6 endpoints)
|
||
|
||
| Method | Endpoint | Açıklama |
|
||
|--------|----------|----------|
|
||
| GET | `/v1/admin/users` | ✅ Tüm kullanıcıları listele |
|
||
| POST | `/v1/admin/users` | ✅ Yeni kullanıcı oluştur (multipart) |
|
||
| GET | `/v1/admin/users/search` | ✅ Kullanıcı ara |
|
||
| GET | `/v1/admin/users/{id}` | ✅ Kullanıcı detayları |
|
||
| PUT | `/v1/admin/users/{id}` | ✅ Kullanıcı güncelle (multipart) |
|
||
| DELETE | `/v1/admin/users/{id}` | ✅ Kullanıcı sil |
|
||
|
||
---
|
||
|
||
### 🎭 Admin - Role Management (2 endpoints)
|
||
|
||
| Method | Endpoint | Açıklama |
|
||
|--------|----------|----------|
|
||
| POST | `/v1/admin/users/{id}/roles` | ✅ Rol ata |
|
||
| DELETE | `/v1/admin/users/{id}/roles/{role}` | ✅ Rol kaldır |
|
||
|
||
---
|
||
|
||
### 📸 Admin - Avatar Management (1 endpoint)
|
||
|
||
| Method | Endpoint | Açıklama |
|
||
|--------|----------|----------|
|
||
| POST | `/v1/admin/users/{id}/avatar` | ✅ Kullanıcı avatar yükle (multipart) |
|
||
|
||
---
|
||
|
||
### 🌐 Admin - CORS Whitelist (2 endpoints)
|
||
|
||
| Method | Endpoint | Açıklama |
|
||
|--------|----------|----------|
|
||
| GET | `/v1/settings/cors/whitelist` | ✅ Whitelist listesi |
|
||
| POST | `/v1/settings/cors/whitelist` | ✅ Whitelist ekle |
|
||
| PUT | `/v1/settings/cors/whitelist/{id}` | ✅ Whitelist güncelle |
|
||
| DELETE | `/v1/settings/cors/whitelist/{id}` | ✅ Whitelist sil |
|
||
|
||
---
|
||
|
||
### 🚫 Admin - CORS Blacklist (2 endpoints)
|
||
|
||
| Method | Endpoint | Açıklama |
|
||
|--------|----------|----------|
|
||
| GET | `/v1/settings/cors/blacklist` | ✅ Blacklist listesi |
|
||
| POST | `/v1/settings/cors/blacklist` | ✅ Blacklist ekle |
|
||
| PUT | `/v1/settings/cors/blacklist/{id}` | ✅ Blacklist güncelle |
|
||
| DELETE | `/v1/settings/cors/blacklist/{id}` | ✅ Blacklist sil |
|
||
|
||
---
|
||
|
||
### ⏱️ Admin - Rate Limit (2 endpoints)
|
||
|
||
| Method | Endpoint | Açıklama |
|
||
|--------|----------|----------|
|
||
| GET | `/v1/settings/ratelimit` | ✅ Rate limit ayarları |
|
||
| PUT | `/v1/settings/ratelimit/{id}` | ✅ Rate limit güncelle |
|
||
|
||
---
|
||
|
||
## 🎯 Swagger UI Erişimi
|
||
|
||
### Browser'da Aç
|
||
```
|
||
http://localhost:8080/docs/index.html
|
||
```
|
||
|
||
### API Dokümantasyonu
|
||
```
|
||
http://localhost:8080/docs/swagger.json
|
||
http://localhost:8080/docs/swagger.yaml
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 Swagger Özeti
|
||
|
||
### Endpoint İstatistikleri
|
||
|
||
```
|
||
📊 Toplam Endpoint'ler: 20
|
||
📊 Toplam Method'lar: 30+
|
||
|
||
🔐 Auth: 7 endpoint
|
||
👤 User: 2 endpoint (avatar)
|
||
👨💼 Admin User Management: 6 endpoint
|
||
🎭 Admin Role Management: 2 endpoint
|
||
📸 Admin Avatar Management: 1 endpoint
|
||
🌐 Admin CORS Whitelist: 2 endpoint
|
||
🚫 Admin CORS Blacklist: 2 endpoint
|
||
⏱️ Admin Rate Limit: 2 endpoint
|
||
```
|
||
|
||
---
|
||
|
||
## 🎨 Swagger Görünümü
|
||
|
||
### Gruplar (Tags)
|
||
|
||
1. **auth** - Authentication endpoints
|
||
2. **User** - User avatar management
|
||
3. **Admin - User Management** - User CRUD operations
|
||
4. **Admin - Settings** - CORS & Rate Limit settings
|
||
|
||
---
|
||
|
||
## ✅ Yeni Eklenen Endpoint'ler
|
||
|
||
### Avatar Upload Endpoints
|
||
|
||
```yaml
|
||
POST /v1/user/avatar
|
||
Summary: Upload user avatar
|
||
Content-Type: multipart/form-data
|
||
Parameters:
|
||
- avatar: file (required)
|
||
Security: Bearer Token
|
||
|
||
DELETE /v1/user/avatar
|
||
Summary: Delete user avatar
|
||
Security: Bearer Token
|
||
|
||
POST /v1/admin/users/{id}/avatar
|
||
Summary: Upload avatar for any user (Admin only)
|
||
Content-Type: multipart/form-data
|
||
Parameters:
|
||
- id: path (user ID)
|
||
- avatar: file (required)
|
||
Security: Bearer Token
|
||
```
|
||
|
||
### Multipart Support
|
||
|
||
```yaml
|
||
POST /v1/admin/users
|
||
Summary: Create new user (Admin only)
|
||
Content-Type: multipart/form-data
|
||
Parameters:
|
||
- email: string (required)
|
||
- password: string (required)
|
||
- user_name: string (required)
|
||
- email_verified: boolean
|
||
- roles: string (comma separated)
|
||
- avatar: file
|
||
|
||
PUT /v1/admin/users/{id}
|
||
Summary: Update user (Admin only)
|
||
Content-Type: multipart/form-data
|
||
Parameters:
|
||
- id: path (user ID)
|
||
- email: string
|
||
- password: string
|
||
- user_name: string
|
||
- email_verified: boolean
|
||
- roles: string (comma separated)
|
||
- avatar: file
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 Swagger Generate Komutu
|
||
|
||
```bash
|
||
cd /Users/beyhan/Desktop/Projeler/Go/AuthCentral
|
||
swag init -g main.go --output ./docs
|
||
```
|
||
|
||
**Otomatik olarak oluşturur:**
|
||
- `docs/docs.go`
|
||
- `docs/swagger.json`
|
||
- `docs/swagger.yaml`
|
||
|
||
---
|
||
|
||
## 📖 Swagger Annotations Örneği
|
||
|
||
### Avatar Upload Handler
|
||
|
||
```go
|
||
// UploadAvatar godoc
|
||
// @Summary Upload user avatar
|
||
// @Tags User
|
||
// @Security ApiKeyAuth
|
||
// @Accept multipart/form-data
|
||
// @Produce json
|
||
// @Param avatar formData file true "Avatar image file"
|
||
// @Success 200 {object} map[string]interface{}
|
||
// @Router /v1/user/avatar [post]
|
||
func (h *AvatarHandler) UploadAvatar(c *gin.Context) {
|
||
// ...
|
||
}
|
||
```
|
||
|
||
### Create User Handler
|
||
|
||
```go
|
||
// CreateUser godoc
|
||
// @Summary Create new user (Admin only)
|
||
// @Tags Admin - User Management
|
||
// @Security ApiKeyAuth
|
||
// @Accept multipart/form-data
|
||
// @Produce json
|
||
// @Param email formData string true "Email"
|
||
// @Param password formData string true "Password"
|
||
// @Param user_name formData string true "Username"
|
||
// @Param email_verified formData boolean false "Email verified"
|
||
// @Param roles formData string false "Roles (comma separated)"
|
||
// @Param avatar formData file false "Avatar image"
|
||
// @Success 201 {object} models.User
|
||
// @Router /v1/admin/users [post]
|
||
func (h *UserManagementHandler) CreateUser(c *gin.Context) {
|
||
// ...
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 Swagger UI'da Test Etme
|
||
|
||
### 1. Swagger UI'ı Açın
|
||
```
|
||
http://localhost:8080/docs/index.html
|
||
```
|
||
|
||
### 2. Authorize Butonuna Tıklayın
|
||
- Token: `Bearer YOUR_TOKEN`
|
||
|
||
### 3. Endpoint Seçin
|
||
- Örnek: `POST /v1/user/avatar`
|
||
|
||
### 4. Try It Out
|
||
- Dosya seçin
|
||
- Execute
|
||
|
||
### 5. Response
|
||
```json
|
||
{
|
||
"message": "Avatar uploaded successfully",
|
||
"avatar_url": "/uploads/avatars/user-id_timestamp.png",
|
||
"user": {
|
||
"id": "...",
|
||
"username": "...",
|
||
"avatar": "/uploads/avatars/user-id_timestamp.png"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 Model Definitions
|
||
|
||
Swagger'da tanımlı modeller:
|
||
|
||
```yaml
|
||
models.User:
|
||
- id: string
|
||
- username: string
|
||
- email: string
|
||
- avatar: string
|
||
- email_verified: boolean
|
||
- created_at: string
|
||
- updated_at: string
|
||
- roles: array[models.Role]
|
||
- social_accounts: array[models.SocialAccount]
|
||
|
||
models.Role:
|
||
- id: integer
|
||
- name: string
|
||
- description: string
|
||
- permissions: array[models.Permission]
|
||
|
||
models.Permission:
|
||
- id: integer
|
||
- name: string
|
||
- description: string
|
||
|
||
models.SocialAccount:
|
||
- id: string
|
||
- user_id: string
|
||
- provider: string
|
||
- provider_id: string
|
||
- email: string
|
||
- name: string
|
||
- avatar_url: string
|
||
|
||
models.CorsWhitelist:
|
||
- id: string
|
||
- origin: string
|
||
- description: string
|
||
- is_active: boolean
|
||
|
||
models.CorsBlacklist:
|
||
- id: string
|
||
- origin: string
|
||
- reason: string
|
||
- is_active: boolean
|
||
|
||
models.RateLimitSetting:
|
||
- id: integer
|
||
- name: string
|
||
- requests_per_minute: integer
|
||
- requests_per_hour: integer
|
||
- is_active: boolean
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ Tamamlandı!
|
||
|
||
### Swagger Özellikleri
|
||
- ✅ 20 Endpoint tamamen dokümante edildi
|
||
- ✅ Multipart/form-data desteği eklendi
|
||
- ✅ Avatar upload endpoint'leri var
|
||
- ✅ Admin user management endpoint'leri var
|
||
- ✅ CORS ve Rate Limit endpoint'leri var
|
||
- ✅ Security (Bearer Token) tanımlı
|
||
- ✅ Model definitions tam
|
||
- ✅ Request/Response examples
|
||
|
||
### Erişim
|
||
```
|
||
🌐 Swagger UI: http://localhost:8080/docs/index.html
|
||
📄 JSON: http://localhost:8080/docs/swagger.json
|
||
📄 YAML: http://localhost:8080/docs/swagger.yaml
|
||
```
|
||
|
||
**Swagger dokümantasyonu eksiksiz! 🎉**
|