beyhan/gobeyhan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Beyhan Oğur
2026-04-26 21:43:40 +03:00
commit f34e54c5a5
100 changed files with 27342 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

794
api_documentation.md Normal file
View File

@@ -0,0 +1,794 @@
# 🚀 Backend API Dokümantasyonu
## 📋 İçindekiler
- [Genel Bilgiler](#genel-bilgiler)
- [Swagger UI](#swagger-ui)
- [Authentication](#authentication)
- [Response Formatı](#response-formatı)
- [Hata Kodları](#hata-kodları)
- [Modüler Yapı](#modüler-yapı)
- [Endpoint'ler](#endpointler)
- [Blog App](#blog-app)
- [Account App](#account-app)
- [Settings App](#settings-app)
---
## Genel Bilgiler
### Base URL
```
http://localhost:8080/api/v1
```
### Content Type
```
Content-Type: application/json
```
### Modüler Yapı
API, **app-based modüler yapı** kullanır:
| App | Sorumluluk | Endpoint Prefix |
|-----|------------|-----------------|
| **Blog** | Kategori, Tag, Post, Yorum | `/api/v1/categories`, `/api/v1/posts` |
| **Account** | Kullanıcı, Rol, İzin | `/api/v1/admin/users`, `/api/v1/admin/roles` |
| **Settings** | CORS, Rate Limit | `/api/v1/admin/cors`, `/api/v1/admin/rate-limits` |
---
## Swagger UI
### Swagger Dokümantasyonu
API'nin interaktif dokümantasyonuna Swagger UI üzerinden erişebilirsiniz:
```
http://localhost:8080/swagger/index.html
```
### Swagger Generate
Swagger dokümantasyonunu güncellemek için:
```bash
# Swagger docs oluştur
swag init
# Veya make komutu ile (varsa)
make swagger
```
### Swagger Annotation Örneği
Handler'larda godoc annotation'lar kullanılır:
```go
// GetAllCategories godoc
// @Summary Get all active categories
// @Description Get list of all active categories
// @Tags blog,categories
// @Accept json
// @Produce json
// @Success 200 {array} models.Category
// @Router /api/v1/categories [get]
func (h *CategoryHandler) GetAllCategories(c *gin.Context) {
// ...
}
```
---
## Authentication
### Kimlik Doğrulama
Admin ve korumalı endpoint'ler için JWT token:
```http
Authorization: Bearer <your_jwt_token>
```
### Erişim Seviyeleri
| Seviye | Açıklama | Örnek |
|--------|----------|-------|
| 🌍 **Public** | Kimlik doğrulama gerektirmez | `GET /api/v1/posts` |
| 🔓 **Auth** | Login olmuş kullanıcı | `POST /api/v1/user/posts/:id/comments` |
| 🔐 **Admin** | Admin rolü gerekli | `POST /api/v1/admin/categories` |
---
## Response Formatı
### Başarılı Response
#### Tekil Kayıt
```json
{
"data": {
"id": 1,
"title": "Örnek"
}
}
```
#### Liste (Pagination ile)
```json
{
"data": [...],
"total": 100,
"page": 1,
"limit": 10
}
```
### Hata Response
```json
{
"error": "Resource not found"
}
```
---
## Hata Kodları
| HTTP Status | Açıklama |
|-------------|----------|
| **200** | Başarılı |
| **201** | Oluşturuldu |
| **400** | Hatalı Request |
| **401** | Yetkisiz |
| **403** | Yasak |
| **404** | Bulunamadı |
| **500** | Sunucu Hatası |
---
## Modüler Yapı
### Kod Organizasyonu
```
app/
├── blog/ → Blog işlevleri
│ ├── handlers/
│ └── services/
├── account/ → Kullanıcı yönetimi
│ ├── handlers/
│ └── services/
└── settings/ → Sistem ayarları
├── handlers/
└── services/
```
### Import Path'leri
```go
import (
blogHandlers "gobeyhan/app/blog/handlers"
blogServices "gobeyhan/app/blog/services"
accountHandlers "gobeyhan/app/account/handlers"
accountServices "gobeyhan/app/account/services"
)
```
---
## Endpoint'ler
## Blog App
Blog uygulaması 5 ana kaynak içerir: Categories, Tags, Posts, Comments, CategoryViews
### 📌 Categories
#### Tüm Kategoriler (Public)
```http
GET /api/v1/categories
```
**Response:**
```json
{
"data": [
{
"id": 1,
"title": "Teknoloji",
"slug": "teknoloji",
"parent": null,
"children": [...]
}
]
}
```
#### Kategori Detay (Public)
```http
GET /api/v1/categories/:slug
```
#### Kategori Görüntülenme (Public)
```http
POST /api/v1/categories/:id/view
```
#### Admin: Kategori CRUD
```http
GET /api/v1/admin/categories
GET /api/v1/admin/categories/:id
POST /api/v1/admin/categories
PUT /api/v1/admin/categories/:id
DELETE /api/v1/admin/categories/:id
GET /api/v1/admin/categories/:id/views
```
**Create Request:**
```json
{
"title": "Yeni Kategori",
"slug": "yeni-kategori",
"description": "Açıklama",
"is_active": true,
"order": 1,
"parent_id": null
}
```
---
### 📌 Tags
#### Tüm Etiketler (Public)
```http
GET /api/v1/tags
```
#### Etiket Detay (Public)
```http
GET /api/v1/tags/:slug
```
#### Admin: Etiket CRUD
```http
GET /api/v1/admin/tags
GET /api/v1/admin/tags/:id
POST /api/v1/admin/tags
PUT /api/v1/admin/tags/:id
DELETE /api/v1/admin/tags/:id
```
**Create Request:**
```json
{
"tag": "golang",
"slug": "golang",
"is_active": true
}
```
---
### 📌 Posts
#### Tüm Yazılar (Public, Paginated)
```http
GET /api/v1/posts?page=1&limit=10
```
**Response:**
```json
{
"data": [
{
"id": 1,
"title": "Blog Yazısı",
"slug": "blog-yazisi",
"user": {...},
"categories": [...],
"tags": [...]
}
],
"total": 100,
"page": 1,
"limit": 10
}
```
#### Yazı Detay (Public)
```http
GET /api/v1/posts/:slug
```
#### Admin: Yazı CRUD
```http
GET /api/v1/admin/posts
GET /api/v1/admin/posts/:id
POST /api/v1/admin/posts
PUT /api/v1/admin/posts/:id
DELETE /api/v1/admin/posts/:id
```
**Create Request:**
```json
{
"title": "Yeni Yazı",
"content": "İçerik...",
"categories": [1, 2],
"tags": [1, 3, 5],
"is_active": true
}
```
---
### 📌 Comments
#### Yazı Yorumları (Public)
```http
GET /api/v1/posts/:id/comments
```
**Response:**
```json
{
"data": [
{
"id": 1,
"user_id": 2,
"body": "Yorum içeriği",
"parent_id": null,
"children": [...]
}
]
}
```
#### Yorum Yaz (Auth)
```http
POST /api/v1/user/posts/:id/comments
Authorization: Bearer <token>
```
**Request:**
```json
{
"body": "Yorum içeriği",
"parent_id": null
}
```
#### Admin: Yorum Yönetimi
```http
GET /api/v1/admin/comments
GET /api/v1/admin/comments/:id
PUT /api/v1/admin/comments/:id
DELETE /api/v1/admin/comments/:id
```
---
## Account App
Kullanıcı, rol ve izin yönetimi
### 📌 Users
#### Admin: Tüm Kullanıcılar
```http
GET /api/v1/admin/users?page=1&limit=10&include_deleted=false
```
**Response:**
```json
{
"data": [
{
"id": 1,
"username": "admin",
"email": "admin@example.com",
"roles": [...],
"social_accounts": [...],
"deleted_at": null
}
],
"total": 50
}
```
#### Admin: Kullanıcı CRUD
```http
GET /api/v1/admin/users/:id
POST /api/v1/admin/users
PUT /api/v1/admin/users/:id
DELETE /api/v1/admin/users/:id # Soft delete
POST /api/v1/admin/users/:id/restore
```
**Create Request:**
```json
{
"email": "user@example.com",
"password": "securePass123",
"username": "newuser"
}
```
> **Not**: Password bcrypt ile hashlenip saklanır
#### Admin: Rol Yönetimi
```http
POST /api/v1/admin/users/:id/roles
DELETE /api/v1/admin/users/:id/roles/:role_id
```
**Assign Role:**
```json
{
"role_id": 2
}
```
---
### 📌 Roles
#### Admin: Roller
```http
GET /api/v1/admin/roles
GET /api/v1/admin/roles/:id
POST /api/v1/admin/roles
PUT /api/v1/admin/roles/:id
DELETE /api/v1/admin/roles/:id
```
**Response:**
```json
{
"data": [
{
"id": 1,
"name": "admin",
"description": "Administrator",
"permissions": [...]
}
]
}
```
**Create Request:**
```json
{
"name": "moderator",
"description": "Moderator role"
}
```
---
### 📌 Permissions
#### Admin: İzinler
```http
GET /api/v1/admin/permissions
POST /api/v1/admin/permissions
```
**Create Request:**
```json
{
"name": "edit_comment",
"description": "Can edit comments"
}
```
---
### 📌 Social Accounts
#### Auth: Kullanıcının Social Hesapları
```http
GET /api/v1/user/social-accounts
DELETE /api/v1/user/social-accounts/:id
```
**Response:**
```json
{
"data": [
{
"id": 1,
"provider": "google",
"provider_user_id": "123456"
}
]
}
```
---
## Settings App
Sistem ayarları ve yapılandırma
### 📌 CORS Whitelist
#### Admin: CORS Whitelist
```http
GET /api/v1/admin/cors/whitelist
POST /api/v1/admin/cors/whitelist
PUT /api/v1/admin/cors/whitelist/:id
DELETE /api/v1/admin/cors/whitelist/:id
```
**Create Request:**
```json
{
"origin": "https://example.com",
"description": "Main website"
}
```
---
### 📌 CORS Blacklist
```http
GET /api/v1/admin/cors/blacklist
POST /api/v1/admin/cors/blacklist
PUT /api/v1/admin/cors/blacklist/:id
DELETE /api/v1/admin/cors/blacklist/:id
```
---
### 📌 Rate Limits
#### Admin: Rate Limit Ayarları
```http
GET /api/v1/admin/rate-limits
PUT /api/v1/admin/rate-limits/:id
```
**Response:**
```json
{
"data": [
{
"id": 1,
"path": "/api/v1/posts",
"max_requests": 100,
"window_seconds": 60
}
]
}
```
**Update Request:**
```json
{
"max_requests": 200,
"window_seconds": 120
}
```
---
### 📌 CORS Cache
#### Admin: Cache Temizle
```http
POST /api/v1/admin/cors/cache/invalidate
```
---
## Endpoint Özeti
### Blog App (29 endpoint)
| Kaynak | Public | Auth | Admin |
|--------|--------|------|-------|
| Categories | 3 | 0 | 6 |
| Tags | 2 | 0 | 5 |
| Posts | 2 | 0 | 5 |
| Comments | 1 | 1 | 4 |
| CategoryViews | 1 | 0 | 1 |
### Account App (17 endpoint)
| Kaynak | Public | Auth | Admin |
|--------|--------|------|-------|
| Users | 0 | 0 | 8 |
| Roles | 0 | 0 | 5 |
| Permissions | 0 | 0 | 2 |
| Social Accounts | 0 | 2 | 0 |
### Settings App (11 endpoint)
| Kaynak | Public | Auth | Admin |
|--------|--------|------|-------|
| CORS Whitelist | 0 | 0 | 4 |
| CORS Blacklist | 0 | 0 | 4 |
| Rate Limits | 0 | 0 | 2 |
| Cache | 0 | 0 | 1 |
**TOPLAM: 57 endpoint**
---
## cURL Örnekleri
### Public Endpoint
```bash
curl http://localhost:8080/api/v1/posts?page=1&limit=5
```
### Admin Endpoint
```bash
curl -X POST http://localhost:8080/api/v1/admin/categories \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title": "Test"}'
```
### Authentication Endpoints
### Register
**POST** `/api/v1/auth/register`
Create a new user account.
**Request Body:**
```json
{
"email": "user@example.com",
"password": "securePass123",
"username": "johndoe"
}
```
**Response:**
```json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": 1,
"email": "user@example.com",
"username": "johndoe",
"avatar": "",
"created_at": "2024-03-20T10:00:00Z"
}
}
```
### Login
**POST** `/api/v1/auth/login`
Authenticate user and get JWT token.
**Request Body:**
```json
{
"email": "user@example.com",
"password": "securePass123"
}
```
**Response:**
```json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": { ... }
}
```
### OAuth Login (Google)
**GET** `/api/v1/auth/google`
Redirects to Google OAuth login page.
**Callback:** `/api/v1/auth/google/callback`
Exchanges code for token and returns JWT + User.
### OAuth Login (GitHub)
**GET** `/api/v1/auth/github`
Redirects to GitHub OAuth login page.
**Callback:** `/api/v1/auth/github/callback`
Exchanges code for token and returns JWT + User.
### Logout
**POST** `/api/v1/auth/logout`
Logout user (client-side token removal recommended).
---
## Blog Endpoints
```bash
curl -X POST http://localhost:8080/api/v1/user/posts/1/comments \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{"body": "Great post!"}'
```
---
## Postman Collection
Environment variables:
```json
{
"base_url": "http://localhost:8080/api/v1",
"admin_token": "eyJhbGc...",
"user_token": "eyJhbGc..."
}
```
---
## Middleware Notları
Auth ve Admin middleware'ler şu anda yorumda:
**Aktif etmek için** [routes.go](file:///Users/beyhan/Desktop/Projeler/Go/gobeyhan/app/routes/routes.go):
```go
// Auth routes
user := api.Group("/user")
user.Use(AuthMiddleware())
// Admin routes
admin := api.Group("/admin")
admin.Use(AuthMiddleware(), AdminMiddleware())
```
---
## Swagger Entegrasyonu
### Kurulum
```bash
go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
```
### Generate
```bash
swag init
```
### Erişim
```
http://localhost:8080/swagger/index.html
```
---
**Last Updated:** 2026-02-11
**Version:** 2.0 (Modular Structure)