یکی از دردسرهای ساخت API اینه که بعد از نوشتن Endpointها تازه باید برای بقیه تیم توضیح بدید هر آدرس چه کاری انجام میده، چه پارامترهایی میگیره، چه داده‌ای باید براش ارسال بشه و خروجی اون چه شکلیه. در پروژه‌ای که فقط چند مسیر داره شاید این کار ساده باشه، اما وقتی تعداد Endpointها بالا میره، مستنداتی که دستی نوشته شدن خیلی راحت از کد اصلی عقب میمونن و ممکنه چیزی که برنامه‌نویس Front-end میخونه با چیزی که API واقعاً انتظار داره متفاوت باشه.

FastAPI بخش زیادی از این مشکل رو خودش حل میکنه. این فریم‌ورک از روی Routeها، نوع پارامترها، مدل‌های Pydantic و اطلاعاتی که هنگام تعریف Endpoint وارد میکنید، توضیح استانداردی از ساختار API تولید میکنه. این توضیح استاندارد OpenAPI Schema نام داره و بعد ابزارهایی مثل Swagger UI میتونن اون رو به یه صفحه تعاملی تبدیل کنن که هم مستندات API رو نشون میده و هم اجازه میده بدون Postman یا نوشتن Front-end، درخواست واقعی برای سرور بفرستید.

Swagger UI در FastAPI چیست؟

Swagger UI رو میشه یه صفحه گرافیکی برای مشاهده و آزمایش API در نظر گرفت. وقتی یه برنامه معمولی FastAPI رو اجرا میکنید، به صورت پیش‌فرض با رفتن به آدرس /docs میتونید این صفحه رو ببینید. FastAPI اطلاعات API رو طبق استاندارد OpenAPI تولید میکنه و Swagger UI هم اون اطلاعات رو میخونه و Endpointها رو به شکل قابل فهم نمایش میده.

مثلاً اگه مسیر GET /users/{user_id} داشته باشید، Swagger UI میتونه مشخص کنه که این Endpoint یه user_id نیاز داره، نوع اون چیه و از چه HTTP Method استفاده میکنه. اگه Endpoint یه Request Body هم داشته باشه، ساختار مورد انتظار اون هم نمایش داده میشه.

تفاوت مهم Swagger UI با یه صفحه مستندات ساده اینه که فقط برای خوندن نیست؛ معمولاً میتونید روی Endpoint موردنظر کلیک کنید، مقدار پارامترها رو وارد کنید، Request رو بفرستید و Response واقعی سرور رو همونجا ببینید.

OpenAPI چه نقشی در این میان دارد؟

گاهی Swagger UI و OpenAPI به جای هم استفاده میشن، در حالی که دقیقاً یه چیز نیستن. OpenAPI یه استاندارد برای توصیف ساختار API هست؛ یعنی مشخص میکنه اطلاعاتی مثل مسیرها، پارامترها، نوع Request و Response و بخش‌های امنیتی چطور توصیف بشن.

Swagger UI یه ابزار نمایشی محسوب میشه که همین اطلاعات استاندارد رو میگیره و به یه رابط قابل استفاده در مرورگر تبدیل میکنه.

FastAPI به صورت پیش‌فرض OpenAPI Schema برنامه رو در /openapi.json ارائه میده. بنابراین اگه اون آدرس رو باز کنید، به جای رابط گرافیکی Swagger UI، ساختار خامی رو میبینید که مشخصات API داخلش قرار گرفته.

در نتیجه جریان کلی این شکلیه: FastAPI کد شما رو بررسی میکنه، OpenAPI Schema میسازه و Swagger UI از همون Schema برای تولید صفحه /docs استفاده میکنه.

چرا Swagger UI برای توسعه‌دهنده مفید است؟

فرض کنید یه Endpoint برای ساخت محصول دارید و Front-end باید برای اون Name، Price و Category ارسال کنه. بدون مستندات مناسب، برنامه‌نویس Front-end باید از شما بپرسه اسم فیلدها چیه، Price عدد صحیح یا اعشاریه و کدوم اطلاعات اجباری هستن.

وقتی مدل ورودی رو درست در FastAPI تعریف کرده باشید، Swagger UI بخش زیادی از همین اطلاعات رو مستقیماً نمایش میده. این موضوع ارتباط بین اعضای تیم رو راحت‌تر میکنه و احتمال اینکه هرکس برداشت متفاوتی از API داشته باشه کمتر میشه.

از طرف دیگه هنگام توسعه خود API هم خیلی کاربردیه، چون بعد از ساخت یه Endpoint لازم نیست فوراً Client جداگانه بنویسید. میتونید /docs رو باز کنید، پارامترها رو وارد کنید و رفتار مسیر رو سریع بررسی کنید.

تست Endpoint در Swagger UI چطور انجام می‌شود؟

داخل صفحه /docs معمولاً Endpointها بر اساس مسیر و HTTP Method نمایش داده میشن. با باز کردن یکی از اون‌ها گزینه‌ای برای فعال کردن حالت آزمایش دارید و بعد میتونید پارامترها یا Request Body موردنیاز رو وارد کنید.

وقتی Request اجرا میشه، Swagger UI معمولاً اطلاعاتی مثل URL درخواست، Response Body، Status Code و Headerهای پاسخ رو نمایش میده. بنابراین برای بررسی اولیه Endpointها ابزار خیلی سریعی محسوب میشه.

البته Swagger UI جای تست خودکار رو نمیگیره. اینکه یه Endpoint رو دستی از /docs اجرا کردید و جواب درست گرفتید، به معنی این نیست که پروژه دیگه به Unit Test یا Integration Test نیاز نداره. Swagger UI بیشتر برای بررسی سریع، شناخت API و آزمایش دستی در زمان توسعه مناسبه.

چطور اطلاعات Swagger UI را حرفه‌ای‌تر کنیم؟

صفحه مستندات زمانی واقعاً مفیده که اطلاعات مناسبی داخلش وجود داشته باشه. اگه فقط ده‌ها Endpoint بدون توضیح داشته باشید، /docs هم بعد از مدتی تبدیل به یه لیست شلوغ میشه.

FastAPI اجازه میده برای کل API اطلاعاتی مثل title، description و version تعریف کنید. برای هر Endpoint هم میشه Summary، Description و Tag مشخص کرد تا مسیرهای مرتبط کنار هم دیده بشن.

یه نمونه ساده:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI(
    title="Store API",
    description="API for managing products and orders",
    version="1.0.0",
    docs_url="/docs",
    redoc_url="/redoc"
)


class Product(BaseModel):
    name: str
    price: float
    in_stock: bool = True


@app.post(
    "/products",
    tags=["Products"],
    summary="Create a new product"
)
async def create_product(product: Product):
    return {
        "message": "Product created",
        "product": product
    }


@app.get(
    "/products/{product_id}",
    tags=["Products"],
    summary="Get product information"
)
async def get_product(product_id: int):
    return {
        "id": product_id,
        "name": "Keyboard",
        "price": 85.5
    }

بعد از اجرای این برنامه و باز کردن /docs، اطلاعات کلی پروژه، Endpointهای محصولات، پارامتر product_id و ساختار مدل Product داخل Swagger UI قابل مشاهده میشه.

نکته مهم اینه که بخش زیادی از این مستندات از همون کدی تولید شده که برنامه برای اعتبارسنجی Request واقعاً ازش استفاده میکنه؛ بنابراین احتمال فاصله گرفتن مستندات از رفتار واقعی API نسبت به یه فایل توضیحات کاملاً دستی کمتر میشه.

ReDoc چیست و چه فرقی با Swagger UI دارد؟

FastAPI به صورت پیش‌فرض یه صفحه مستندات دیگه هم در /redoc ارائه میده که توسط ReDoc ساخته میشه. مستندات رسمی FastAPI هر دو رابط رو به صورت پیش‌فرض در اختیار برنامه قرار میدن: Swagger UI در /docs و ReDoc در /redoc.

Swagger UI بیشتر برای تعامل و آزمایش مستقیم Endpointها معروفه، در حالی که ReDoc معمولاً برای مطالعه ساختار API ظاهر مستندمحورتری داره. هر دو از OpenAPI Schema استفاده میکنن؛ بنابراین لازم نیست برای هرکدوم مستندات جداگانه‌ای تولید کنید.

آیا می‌توان آدرس /docs را تغییر داد؟

بله. آدرس Swagger UI اجباری نیست و میشه اون رو هنگام ساخت برنامه FastAPI تغییر داد. مثلاً اگه به جای /docs بخواید مستندات روی /documentation باشه، میشه مقدار docs_url رو تغییر داد.

برای ReDoc هم redoc_url وجود داره و آدرس OpenAPI Schema با openapi_url قابل تنظیمه. مستندات رسمی FastAPI همچنین اجازه میدن Swagger UI یا ReDoc رو با قرار دادن مقدار مربوطه روی None غیرفعال کنید. اگه openapi_url=None قرار بگیره، خود OpenAPI Schema غیرفعال میشه و رابط‌هایی که برای کار کردن به اون وابسته هستن هم از دسترس خارج میشن.

آیا باید Swagger UI را در Production غیرفعال کنیم؟

برای بعضی پروژه‌ها تیم توسعه ترجیح میده مستندات تعاملی عمومی روی سرور Production در دسترس نباشه، مخصوصاً وقتی API صرفاً برای استفاده داخلی طراحی شده. FastAPI امکان غیرفعال کردن یا تغییر مسیر این صفحات رو فراهم میکنه، اما یه نکته مهم نباید فراموش بشه: مخفی کردن /docs سیستم امنیتی محسوب نمیشه.

اگه Endpoint خصوصی دارید، باید با Authentication و Authorization واقعی محافظت بشه. تغییر /docs به یه آدرس عجیب یا حذف صفحه Swagger UI باعث نمیشه مسیرهای اصلی API امن بشن.

بنابراین تصمیم درباره فعال یا غیرفعال بودن مستندات Production به معماری پروژه بستگی داره، ولی امنیت Endpointها باید مستقل از این تصمیم طراحی شده باشه.

Swagger UI با JWT و Authentication هم کار می‌کند؟

بله. یکی از مزیت‌های ترکیب ابزارهای امنیتی FastAPI با OpenAPI اینه که اطلاعات Security Scheme میتونه وارد مستندات API بشه. در چنین شرایطی Swagger UI میتونه امکان وارد کردن اطلاعات احراز هویت رو در اختیار توسعه‌دهنده قرار بده تا Endpointهای محافظت‌شده هم از داخل مستندات آزمایش بشن.

FastAPI حتی برای سناریوهای OAuth2 امکاناتی در رابط مستندات خودش در نظر گرفته و مستندات رسمی روش سفارشی‌سازی Swagger UI و OAuth2 Redirect رو هم توضیح میدن.

این ویژگی مخصوصاً در پروژه‌ای که تعداد زیادی Endpoint خصوصی داره مفیده، چون لازم نیست برای هر Request به صورت دستی Header امنیتی رو در ابزارهای مختلف آماده کنید.

اشتباه رایج؛ فکر کردن به Swagger UI به عنوان مستندات کامل پروژه

Swagger UI مستندات فنی Endpointها رو خیلی خوب نمایش میده، اما قرار نیست تمام دانش پروژه رو جایگزین کنه. مثلاً ممکنه API شما قوانین تجاری خاصی داشته باشه که فقط از روی مدل Request قابل فهم نباشه؛ مثل اینکه سفارش فقط در ساعت خاصی قابل لغوه یا یه عملیات برای کاربران با سطح دسترسی مشخص انجام میشه.

این نوع قوانین باید در Descriptionهای مناسب یا مستندات تکمیلی پروژه توضیح داده بشن. بهتره Swagger UI رو مرجع فنی زنده API بدونیم، نه جایگزین تمام مستندات معماری و منطق کسب‌وکار.

جمع‌بندی

Swagger UI یکی از قابلیت‌های کاربردی FastAPI برای مشاهده و تست API بدون ساخت ابزار جداگانه‌ست. FastAPI اطلاعات Endpointها، پارامترها و مدل‌ها رو طبق استاندارد OpenAPI توصیف میکنه و Swagger UI از همین اطلاعات برای ساخت صفحه تعاملی /docs استفاده میکنه. ReDoc هم به عنوان رابط جایگزین به صورت پیش‌فرض در /redoc ارائه میشه و OpenAPI Schema خام معمولاً در /openapi.json در دسترسه.

با تعریف درست مدل‌های Pydantic، Tag، Summary و اطلاعات کلی پروژه، میشه مستنداتی ساخت که هم برای توسعه‌دهنده Back-end مفید باشه و هم Front-end یا مصرف‌کننده API سریع بفهمه هر Endpoint چه ورودی و خروجی‌ای داره.

در نهایت مزیت اصلی این قابلیت فقط ظاهر خوب /docs نیست؛ مستندات از ساختار واقعی API ساخته میشن و همزمان میشه همون API رو مستقیماً از مرورگر آزمایش کرد.