arc/docs/SWAGGER_CUSTOMIZATION.md

📚 راهنمای سفارسی‌سازی Swagger UI حسابیکس

🎯 خلاصه تغییرات

این سند خلاصه‌ای از تغییرات انجام شده برای بهبود ظاهر و خوانایی Swagger UI در پروژه حسابیکس است.

✨ ویژگی‌های جدید

1️⃣ پشتیبانی کامل از زبان فارسی

• ✅ فونت Vazirmatn برای متن‌های فارسی
• ✅ فونت JetBrains Mono برای کدها
• ✅ خوانایی بهتر و حروف جدا شده

2️⃣ پشتیبانی RTL (راست به چپ)

• ✅ راست‌چین شدن تمام توضیحات فارسی
• ✅ چپ‌چین ماندن کدها و URL ها
• ✅ تنظیم صحیح Margin و Padding

3️⃣ رنگ‌بندی برند حسابیکس

• ✅ رنگ اصلی: #366092 (آبی حسابیکس)
• ✅ هماهنگی با هویت بصری برند
• ✅ رنگ‌بندی متفاوت برای متدهای HTTP

4️⃣ بهبود UI/UX

• ✅ دکمه‌های مدرن با سایه و انیمیشن
• ✅ Input fields حرفه‌ای
• ✅ Syntax Highlighting بهتر
• ✅ Scrollbar سفارشی
• ✅ Responsive Design

5️⃣ دسته‌بندی بهتر

• ✅ آیکون برای هر دسته (Tag)
• ✅ Border رنگی برای تشخیص بهتر
• ✅ Hover effects

📂 ساختار فایل‌ها

hesabixAPI/
├── app/
│   └── main.py                          # تغییرات اصلی
├── assets/
│   ├── swagger/
│   │   ├── custom.css                   # استایل‌های سفارشی اصلی
│   │   ├── swagger-rtl.css              # پشتیبانی RTL
│   │   └── README.md                    # راهنمای دایرکتوری
│   └── logo-blue.png                    # لوگو (موجود)
└── SWAGGER_CUSTOMIZATION.md             # این فایل

🚀 نحوه استفاده

دسترسی به مستندات

پس از اجرای سرور، سه مسیر در دسترس است:

1. Swagger UI استاندارد

http://localhost:8000/docs

یا

https://agent.hesabix.ir/docs

• نسخه استاندارد FastAPI
• بدون استایل سفارشی

2. Swagger UI سفارشی (پیشنهادی) ⭐

http://localhost:8000/docs-custom

یا

https://agent.hesabix.ir/docs-custom

• استایل حرفه‌ای حسابیکس
• پشتیبانی کامل فارسی و RTL
• بهترین تجربه کاربری

3. ReDoc

http://localhost:8000/redoc

یا

https://agent.hesabix.ir/redoc

• مستندات با ReDoc
• مناسب برای چاپ

🔧 تغییرات انجام شده

در main.py

✅ Import های جدید

from fastapi.staticfiles import StaticFiles
from fastapi.responses import HTMLResponse
from fastapi.openapi.docs import get_swagger_ui_html

✅ تنظیمات Swagger UI

application = FastAPI(
    # ... سایر تنظیمات
    docs_url=None,  # غیرفعال کردن docs پیش‌فرض
    swagger_ui_parameters={
        "defaultModelsExpandDepth": -1,
        "docExpansion": "list",
        "filter": True,
        "persistAuthorization": True,
        "displayRequestDuration": True,
        "tryItOutEnabled": True,
        "syntaxHighlight.theme": "monokai",
        "deepLinking": True,
        "displayOperationId": False,
    },
)

✅ Mount کردن Assets

application.mount("/assets", StaticFiles(directory="assets"), name="assets")

✅ Endpoint های سفارشی

• /docs - نسخه استاندارد
• /docs-custom - نسخه سفارشی با HTML کامل

🎨 سفارسی‌سازی بیشتر

تغییر رنگ اصلی

در assets/swagger/custom.css:

:root {
  --hesabix-primary: #YOUR_COLOR;
  --hesabix-primary-dark: #YOUR_DARK_COLOR;
  --hesabix-primary-light: #YOUR_LIGHT_COLOR;
}

تغییر فونت

@font-face {
  font-family: 'YourFont';
  src: url('/assets/fonts/YourFont.woff2') format('woff2');
}

.swagger-ui * {
  font-family: 'YourFont', Tahoma, Arial, sans-serif !important;
}

اضافه کردن لوگوی جدید

1. لوگو را در assets/ قرار دهید
2. در custom.css تغییر دهید:

.swagger-ui .topbar .topbar-wrapper::before {
  background-image: url('/assets/your-new-logo.png');
}

📊 مقایسه Before/After

ویژگی	قبل ❌	بعد ✅
فونت فارسی	نامناسب، حروف به هم چسبیده	Vazirmatn، خوانا و زیبا
جهت متن	چپ‌چین (LTR)	راست‌چین (RTL)
رنگ‌بندی	سبز استاندارد Swagger	آبی حسابیکس (#366092)
لوگو	❌ ندارد	✅ لوگو حسابیکس در Topbar
دکمه‌ها	ساده	مدرن با سایه و انیمیشن
جستجو	غیرفعال	✅ فعال
Try It Out	بدون زیباسازی	طراحی حرفه‌ای
Responsive	محدود	✅ کاملاً Responsive

🧪 تست و عیب‌یابی

چک کردن CSS ها

# بررسی وجود فایل‌ها
ls -la assets/swagger/

# خروجی باید شامل این موارد باشد:
# - custom.css
# - swagger-rtl.css
# - README.md

تست در مرورگر

1. به http://localhost:8000/docs-custom بروید
2. Developer Tools را باز کنید (F12)
3. در Console بررسی کنید که خطایی وجود نداشته باشد
4. در Network Tab بررسی کنید که CSS ها لود شده باشند

مشکلات رایج

مشکل: CSS ها لود نمی‌شوند

علت: مسیر assets درست mount نشده راه‌حل:

# در main.py بررسی کنید:
application.mount("/assets", StaticFiles(directory="assets"), name="assets")

مشکل: فونت فارسی نمایش داده نمی‌شود

علت: اتصال اینترنت یا مشکل CDN راه‌حل: فونت را به صورت local در assets/fonts/ قرار دهید

مشکل: تغییرات نمایش داده نمی‌شوند

راه‌حل:

# پاک کردن cache مرورگر
Ctrl + Shift + R  # Windows/Linux
Cmd + Shift + R   # Mac

# یا استفاده از Incognito Mode

🔄 به‌روزرسانی

برای به‌روزرسانی Swagger UI به نسخه جدید:

<!-- در endpoint /docs-custom تغییر دهید: -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.x.x/swagger-ui.css">
<script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.x.x/swagger-ui-bundle.js"></script>

📦 Production Deployment

1. Minify کردن CSS

# نصب ابزار minify
npm install -g clean-css-cli

# minify کردن فایل‌ها
cleancss -o assets/swagger/custom.min.css assets/swagger/custom.css
cleancss -o assets/swagger/swagger-rtl.min.css assets/swagger/swagger-rtl.css

2. استفاده از CDN

برای بهبود performance در production، می‌توانید CSS های خود را روی CDN قرار دهید:

<link rel="stylesheet" href="https://your-cdn.com/swagger/custom.min.css">
<link rel="stylesheet" href="https://your-cdn.com/swagger/swagger-rtl.min.css">

3. تنظیمات Caching

در Nginx یا Apache:

# Nginx
location /assets/swagger/ {
    expires 30d;
    add_header Cache-Control "public, immutable";
}

📝 چک‌لیست Deploy

• فایل‌های CSS ایجاد شده‌اند
• main.py به‌روزرسانی شده
• دایرکتوری assets/swagger/ وجود دارد
• سرور restart شده
• /docs-custom در مرورگر تست شده
• Cache مرورگر پاک شده
• در Production تست شده
• CSS ها minify شده‌اند (اختیاری)

🤝 مشارکت

اگر پیشنهاد بهبود یا ایده جدیدی دارید:

1. Issue جدید در GitLab/GitHub ایجاد کنید
2. تغییرات را در branch جدید commit کنید
3. Pull/Merge Request ارسال کنید

📚 منابع

• Swagger UI Customization
• FastAPI Custom Docs
• Vazirmatn Font
• CSS RTL Best Practices

🆘 پشتیبانی

برای سوالات یا مشکلات:

• ایمیل: support@hesabix.ir
• تیکت: در سیستم پشتیبانی حسابیکس

---

✨ نسخه: 1.0.0
📅 تاریخ: دسامبر 2025
👥 تیم: حسابیکس
📄 لایسنس: GNU GPLv3