# ✅ 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! 🎉**