first commit
This commit is contained in:
Beyhan Oğur
357
SWAGGER_DOCUMENTATION.md
Normal file
357
SWAGGER_DOCUMENTATION.md
Normal file
@@ -0,0 +1,357 @@
|
||||
# ✅ 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! 🎉**
|
||||
Reference in New Issue
Block a user