در بحبوحه یک پروژه مهاجرت در محل کار من، جایی که ما در حال انتقال یک برنامه وب از چارچوب دات نت به معماری Python + React هستیم، با یک چالش مهم روبرو شدیم که مانع پیشرفت ما شد: عدم وجود برنامه جامع و به روز. اسناد API همانطور که ما این مهاجرت پشته فناوری را شروع کردیم، درک منطق پشت اعتبارسنجی نقطه داده در هنگام توسعه APIها بسیار مهم شد. با این حال، فقدان مستندات API دقیق و به روز یک مانع بزرگ بود.
در طول سال‌ها تجربه‌ام، متوجه شده‌ام که حفظ APIها می‌تواند یک کار دلهره‌آور باشد. این امر مستلزم تلاش و توجه مداوم است تا اطمینان حاصل شود که آنها نیازهای در حال تحول کسب و کار را برآورده می کنند و با چشم انداز تکنولوژیکی در حال تغییر همگام می مانند. در سفرم، با چندین چالش مهم روبرو شده ام که توانایی من را برای نگهداری موثر API ها آزمایش کرده است. بیایید این چالش ها را بررسی کنیم.
چالش ها
سازگاری و دقت
حفظ ثبات و دقت در اسناد API بسیار مهم است. با این حال، اطمینان از اینکه اسناد به طور دقیق وضعیت فعلی API را منعکس می کند، می تواند چالش برانگیز باشد. همانطور که به روز رسانی ها و تغییرات ایجاد می شود، همگام نگه داشتن اسناد به یک کار سخت تبدیل می شود.مدیریت تغییرات API
همانطور که نیازهای کسب و کار تکامل می یابد، API ها باید مطابق با آن سازگار شوند. ایجاد تغییرات در APIها در حالی که به حداقل رساندن اختلال در ادغام های موجود می تواند پیچیده باشد. برقراری ارتباط و مدیریت صحیح این تغییرات برای به حداقل رساندن تأثیر بر مصرف کنندگان API حیاتی است.پیچیدگی مستندات
API ها می توانند گردش کار پیچیده، نقاط پایانی متعدد و پارامترهای ورودی/خروجی مختلفی داشته باشند. مستندسازی چنین پیچیدگی به شیوه ای واضح و مختصر می تواند سخت باشد. ایجاد تعادل مناسب بین ارائه جزئیات کافی برای توسعه دهندگان با حفظ سادگی می تواند یک چالش مهم باشد.حاکمیت و امنیت API
ایجاد و حفظ حاکمیت و اقدامات امنیتی مناسب API برای محافظت از داده های حساس و جلوگیری از دسترسی غیرمجاز ضروری است. پیاده‌سازی مکانیسم‌های احراز هویت و مجوز امن، مدیریت کنترل دسترسی، و نظارت بر استفاده از API نیازمند توجه و هوشیاری مداوم است.
در تلاشم برای یافتن راه‌حل‌های بهتر برای پرداختن به چالش‌های نگهداری API، با DRF-YASG (چارچوب استراحت Django – با این حال یک Swagger Generator) برخورد کردم. این ابزار قدرتمند فرآیند تولید و نگهداری اسناد API را ساده می‌کند و راه‌حلی جامع برای مقابله با چالش‌هایی که قبلاً با آنها مواجه بودم ارائه می‌دهد.
1. مقدمه (DRF-YASG چیست)
DRF-YASG، مخفف Django Rest Framework – Yet Another Swagger Generator، ابزاری قابل توجه است که فرآیند تولید و نگهداری اسناد API را ساده می کند. DRF-YASG که به طور خاص برای چارچوب استراحت جنگو طراحی شده است، تولید اسناد API تعاملی را بر اساس مشخصات OpenAPI (که قبلاً Swagger نامیده می شد) خودکار می کند.
2. چرا DRF-YASG؟
DRF-YASG می تواند به عنوان یک راه حل واحد برای تمام چالش هایی که در بالا ذکر کردم عمل کند.
سازگاری و دقت
DRF-YASG فرآیند تولید اسناد API را با استخراج خودکار اطلاعات از سریال‌سازها، نماها و مجموعه‌های نمایشی جنگو Rest Framework ساده می‌کند. این تضمین می کند که مستندات با اجرای واقعی API مطابقت دارند و خطر ناهماهنگی و عدم دقت را کاهش می دهند.مدیریت تغییرات API
DRF-YASG به‌طور خودکار اسناد API را هنگامی که تغییراتی در پایگاه کد زیربنایی Django Rest Framework ایجاد می‌شود، به‌روزرسانی می‌کند. این به همگام نگه داشتن اسناد با وضعیت فعلی API کمک می کند، حتی در هنگام ایجاد تغییراتی مانند افزودن یا اصلاح نقاط پایانی، پارامترها یا ساختارهای پاسخ.پیچیدگی مستندات
DRF-YASG مستندات تعاملی و کاربرپسند را بر اساس مشخصات OpenAPI (که قبلاً Swagger نامیده می شد) تولید می کند. این پیچیدگی مستندسازی گردش‌های کاری پیچیده، نقاط پایانی و پارامترها را کنترل می‌کند و یک رابط واضح و شهودی برای توسعه‌دهندگان برای درک و تعامل با API فراهم می‌کند.حاکمیت و امنیت API
DRF-YASG از ادغام مکانیسم‌های احراز هویت و مجوز ارائه شده توسط Django Rest Framework پشتیبانی می‌کند و اجرای قوانین و اقدامات امنیتی API را آسان‌تر می‌کند. این امکان گنجاندن طرح‌های احراز هویت، مجوزها و جزئیات کنترل دسترسی را در اسناد تولید شده فراهم می‌کند و استفاده امن API را ترویج می‌کند.
3. افزودن DRF-YASG به جنگو: قفل Swagger Magic را باز کنید
با نصب DRF-YASG در پروژه جنگو شروع کنید. می توانید این کار را با استفاده از pip، مدیر بسته پایتون، با اجرای دستور زیر انجام دهید:
pip install drf-yasg
- مرحله 2: پیکربندی Django Rest Framework
برای فعال کردن DRF-YASG، مطمئن شوید که چارچوب استراحت جنگو را به درستی در پروژه جنگو خود پیکربندی کرده اید. این شامل افزودن بسته‌ها و تنظیمات لازم به فایل settings.py است.
شما باید DRF-YASG را در برنامه های نصب شده خود در پروژه اضافه کنید settings.py فایل.
INSTALLED_APPS = [
...Rest of Installed Apps
'drf_yasg'
]
- مرحله 3: URL های DRF-YASG را وارد کنید
در مرحله بعد، باید URL های DRF-YASG را در پیکربندی URL پروژه جنگو خود بگنجانید. فایل urls.py پروژه خود را باز کنید و عبارت import زیر را در بالا اضافه کنید:
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
سپس، یک نمای طرحواره ایجاد کنید و آن را با اطلاعات API خود پیکربندی کنید. کد زیر را به فایل urls.py خود اضافه کنید:
schema_view = get_schema_view(
openapi.Info(
title="Your API Title",
default_version="v1",
description="Your API description",
terms_of_service="https://example.com/terms/",
contact=openapi.Contact(email="[email protected]"),
license=openapi.License(name="MIT License"),
),
public=True,
)
urlpatterns = [
# Your existing URL patterns
# ...
path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name="schema-swagger-ui"),
path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name="schema-redoc"),
]
- مرحله 4: API های خود را به روز کنید
اگر یک تابع نمای جنگو یا نمای کلاسی دارید که نقطه پایانی API شما را نشان می دهد. برای ارائه اسناد Swagger اضافی، می‌توانید دکوراتور @swagger_auto_schema را در بالای این تابع view یا کلاس اضافه کنید.
@swagger_auto_schema(
method='post',
request_body=openapi.Schema(
type=openapi.TYPE_OBJECT,
properties={
'name': openapi.Schema(type=openapi.TYPE_STRING),
'email': openapi.Schema(type=openapi.TYPE_STRING),
},
required=['name', 'email']
),
responses={
201: 'Created',
400: 'Bad Request',
}
)
@api_view(['POST'])
def create_user(request):
# Your implementation here
pass
در اینجا هر استدلال در دکوراتور چه کاری انجام می دهد:
روش: روش(های) HTTP را مشخص می کند که مستندات Swagger باید برای آن تولید شود. در این مورد، برای مستندسازی روش POST، آن را روی ‘post’ تنظیم می کنیم.
request_body: طرح بدنه درخواست را برای نقطه پایانی API توصیف می کند. ما یک طرحواره شی با دو ویژگی نام و ایمیل، هر دو از نوع رشته تعریف می کنیم. همچنین مشخص می کنیم که هر دو ویژگی مورد نیاز است.
پاسخ ها: پاسخ های مورد انتظار را برای نقطه پایانی API تعریف می کند. در این حالت، برای ایجاد موفقیت آمیز پاسخ 201 و برای درخواست بد، پاسخ 400 را مشخص می کنیم.
شما می توانید سفارشی کنید request_body و responsesبا توجه به نیازهای نقطه پایانی API خاص شما.
- مرحله 5: دسترسی به APIهای متجاوز و اسناد آن:
تبریک می گویم، شما API های خود را با موفقیت به دست آوردید. اکنون می‌توانید روی توسعه نقاط پایانی API تمرکز کنید و به DRF-YASG اجازه دهید این کار را برای مستندسازی انجام دهد.
می‌توانید از نقاط پایانی که در urls.py خود ایجاد کرده‌اید، به UI swagger دسترسی داشته باشید.
تصویر زیر نشان می دهد که چگونه UI از swaggerو redocبه نظر می رسد:
Swagger UI:
redoc UI:
Swagger UI طیف وسیعی از ویژگی ها و عملکردها را ارائه می دهد که به شما امکان می دهد با API ها تعامل داشته باشید و آن ها را کاوش کنید. در اینجا برخی از کارهای اصلی وجود دارد که می توانید در Swagger UI انجام دهید:
Browse API Endpoints: Swagger UI فهرستی از نقاط پایانی API موجود را ارائه می‌کند که پیمایش و یافتن نقطه پایانی مورد نظر را آسان می‌کند.
مشاهده اسناد API: Swagger UI مستندات دقیق را برای هر نقطه پایانی API، از جمله پارامترهای درخواست، سرصفحه‌ها و طرح‌واره‌های پاسخ نمایش می‌دهد.
تست تماس‌های API: می‌توانید با وارد کردن پارامترهای مورد نیاز و اجرای درخواست، تماس‌های API را مستقیماً از Swagger UI برقرار کنید. پاسخ در رابط نمایش داده می شود.
روش‌های HTTP را انتخاب کنید: رابط کاربری Swagger از روش‌های مختلف HTTP (GET، POST، PUT، DELETE، و غیره) برای تماس‌های API پشتیبانی می‌کند. شما می توانید روش مناسب را برای هر نقطه پایانی انتخاب کنید.
ارائه پارامترهای درخواست: رابط کاربری Swagger به شما امکان می دهد پارامترهای لازم را برای تماس API وارد کنید، مانند پارامترهای پرس و جو، پارامترهای مسیر، و درخواست داده های بدن.
پیکربندی سرصفحه‌های درخواست: می‌توانید سرصفحه‌های سفارشی را برای درخواست‌های API تنظیم کنید، مانند نشانه‌های احراز هویت یا انواع محتوا.
Handle Authentication: Swagger UI گزینه‌هایی را برای انجام احراز هویت، از جمله احراز هویت اولیه، احراز هویت کلید API یا OAuth فراهم می‌کند. می توانید اعتبارنامه ها یا نشانه های مورد نیاز را برای نقاط پایانی تأیید شده وارد کنید.
Handle Response Codes: Swagger UI کدهای پاسخ ممکن را برای هر تماس API نمایش می دهد. می توانید کد پاسخ، توضیحات و طرح پاسخ مرتبط را مشاهده کنید.
مشاهده نمونه‌های درخواست: رابط کاربری Swagger می‌تواند نمونه‌های درخواست را نشان دهد و به شما امکان می‌دهد ساختار و قالب مورد انتظار بار درخواست را ببینید.
مشاهده نمونه‌های پاسخ: رابط کاربری Swagger می‌تواند نمونه‌های پاسخ را نمایش دهد و پاسخ‌های نمونه را بر اساس طرح پاسخ نشان دهد.
تعامل با مقادیر شمارش شده: اگر نقطه پایانی مقادیری را برای پارامترهای خاصی برشمرده است، Swagger UI گزینه‌های کشویی یا تکمیل خودکار را برای انتخاب مقادیر مناسب ارائه می‌کند.
صفحه‌بندی Handle: اگر یک API از صفحه‌بندی پشتیبانی می‌کند، Swagger UI گزینه‌هایی را برای تعیین اندازه صفحه و پیمایش در نتایج صفحه‌بندی شده ارائه می‌کند.
ذخیره و اشتراک‌گذاری درخواست‌ها: Swagger UI به شما امکان می‌دهد درخواست‌های API را ذخیره و به اشتراک بگذارید و آن را برای اهداف همکاری یا مستندسازی راحت می‌کند.
دانلود تعریف API: Swagger UI گزینه هایی را برای دانلود فایل مشخصات OpenAPI/Swagger (در فرمت JSON یا YAML) برای API فراهم می کند.
عملکرد جستجو: Swagger UI شامل یک نوار جستجو است که به شما امکان می دهد به سرعت نقاط پایانی، پارامترها یا عملیات خاصی را در اسناد API جستجو کنید.
جابه‌جایی بین نسخه‌های API: اگر چندین نسخه از یک API مستند شده باشد، Swagger UI به شما امکان می‌دهد بین نسخه‌های مختلف جابجا شوید تا نقاط پایانی خاص هر نسخه را بررسی کنید.
نتیجه:
در نتیجه، DRF-YASG یک ابزار ضروری برای مستندسازی API های جنگو است. ادغام آن با Django REST Framework و توانایی تولید اسناد API تعاملی با استفاده از مشخصات OpenAPI (Swagger) آن را به یک دارایی ارزشمند برای توسعه دهندگان تبدیل کرده است. با DRF-YASG، می توانید در زمان صرفه جویی کنید، مستندات جامع ایجاد کنید و تجربه کلی توسعه دهنده API خود را ارتقا دهید.
با تشکر از شما برای خواندن! اگر سوالی یا بازخوردی در مورد این مقاله دارید، لطفاً در نظرات خود دریغ نکنید. من همیشه به دنبال پیشرفت هستم و دوست دارم از شما بشنوم.
همچنین، اگر از این محتوا لذت بردید و می‌خواهید در پست‌های بعدی به‌روز باشید، در لینکدین با من در ارتباط باشید و من را دنبال کنید. توییتر و نمایه Github من را بررسی کنید.
