وثائق FastAPI: الدليل الشامل لتطوير واجهات برمجة التطبيقات بسرعة وسهولة

هل شعرت يومًا بالارتباك بسبب التعقيد الهائل لوثائق API؟ أنت لست وحدك! سواء كنت مطورًا ذو خبرة أو مبتدئًا فقط، يمكن أن يكون التنقل خلال تفاصيل تطوير API مهمة شاقة. لكن لا تخف، لأننا اليوم سوف نغوص في وثائق FastAPI، الأداة المصممة لجعل حياتك أسهل بكثير.

ما هو FastAPI؟

FastAPI هو إطار عمل ويب حديث وسريع (عالي الأداء) لبناء APIs باستخدام Python 3.6+ استنادًا إلى تلميحات نوع Python القياسية. تم تصميمه ليكون سهل الاستخدام وبديهيًا مع ضمان بقاء كودك قويًا وسهل الصيانة. سرعة FastAPI تتساوى مع Node.js و Go وغالبًا ما تكون أسرع من العديد من أطر العمل الأخرى في Python. يتحقق ذلك بفضل استخدامه للبرمجة غير المتزامنة وتلميحات الأنواع.

لماذا تختار FastAPI؟

اختيار FastAPI لتطوير API الخاص بك له العديد من الفوائد:

1. السرعة: FastAPI هو أحد أسرع أطر عمل الويب في Python.
2. سهولة الاستخدام: الوثائق شاملة وسهلة المتابعة.
3. تحقق البيانات: مع Pydantic، يقوم FastAPI تلقائيًا بالتحقق من بيانات الطلب.
4. دعم غير متزامن: يدعم FastAPI البرمجة غير المتزامنة بشكل أصلي.
5. توثيق تلقائي: يولد FastAPI وثائق واجهة برمجة التطبيقات التفاعلية باستخدام Swagger UI و ReDoc.

البدء مع FastAPI

التثبيت

أول الأشياء أولاً، تحتاج إلى تثبيت FastAPI وخادم ASGI لخدمة تطبيقك. Uvicorn هو خيار رائع لذلك.

pip install fastapi
pip install uvicorn

إنشاء أول API لك

دعنا نغوص في إنشاء API بسيطة. أنشئ ملف Python جديد يسمى main.py وأضف الكود التالي:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

لتشغيل التطبيق، استخدم الأمر التالي:

uvicorn main:app --reload

قم بزيارة http://127.0.0.1:8000 في متصفحك، ويجب أن ترى {"Hello": "World"}. مبروك، لقد قمت بتو إنشاء أول تطبيق FastAPI لك!

استكشاف الوثائق التي تم إنشاؤها تلقائيًا

واحدة من الميزات البارزة في FastAPI هي الوثائق التفاعلية التي يتم إنشاؤها تلقائيًا. يقوم FastAPI بإنشاء نوعين من الوثائق بشكل افتراضي:

1. Swagger UI: متاح على http://127.0.0.1:8000/docs
2. ReDoc: متاح على http://127.0.0.1:8000/redoc

تعتبر هذه الوثائق مفيدة للغاية لاختبار API الخاص بك ومشاركتها مع فريقك.

تمرير المعلمات في FastAPI

يتيح لك FastAPI تمرير المعلمات بسهولة في نقاط نهاية API الخاصة بك. يمكنك تمرير المعلمات بطرق مختلفة، مثل معلمات المسار، ومعلمات الاستعلام، وأجسام الطلب.

معلمات المسار

تُستخرج معلمات المسار من مسار URL. على سبيل المثال، في URL /items/{item_id}، item_id هو معلمة مسار.

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

معلمات الاستعلام

معلمات الاستعلام تُستخرج من سلسلة الاستعلام. على سبيل المثال، في URL /items/?q=search، q هي معلمة استعلام.

@app.get("/items/")
def read_item(q: str = None):
    return {"q": q}

أجسام الطلب

تُستخدم أجسام الطلب لإرسال البيانات إلى الخادم. يجعل FastAPI من السهل العمل مع أجسام JSON.

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None

@app.post("/items/")
def create_item(item: Item):
    return item

أفضل الممارسات لوثائق FastAPI

إنشاء وثائق شاملة وسهلة الاستخدام أمر ضروري لأي API. إليك بعض أفضل الممارسات التي يجب اتباعها عند توثيق تطبيق FastAPI الخاص بك:

استخدام عناوين واضحة ووصفية

تأكد من أن عناوينك تصف بوضوح نقاط النهاية ووظائفها. يساعد ذلك المستخدمين على فهم غرض كل نقطة نهاية بسرعة.

توفير أوصاف مفصلة

قم بتضمين أوصاف مفصلة لنقاط النهاية والمعلمات وأجسام الطلب/الاستجابة. يساعد ذلك المستخدمين على فهم كيفية استخدام API الخاصة بك بشكل فعال.

تضمين أمثلة

يمكن أن تكون تقديم أمثلة على الطلبات والاستجابات مفيدة للغاية للمستخدمين. توضح الأمثلة كيفية استخدام نقاط النهاية وما يمكن توقعه في المقابل.

استغلال ميزات توثيق FastAPI

يوفر FastAPI العديد من الميزات المدمجة لتعزيز وثائقك. استخدم هذه الميزات لإنشاء وثائق شاملة وتفاعلية.

الفعاليات

يمكنك تجميع نقاط النهاية باستخدام الفعاليات. تساعد الفعاليات في تنظيم وثائقك وتجعل من السهل التنقل.

@app.get("/items/", tags=["items"])
def read_items():
    return ["item1", "item2"]

الملخصات والأوصاف

يمكنك إضافة ملخصات وأوصاف إلى نقاط النهاية الخاصة بك لتوفير مزيد من السياق.

@app.post("/items/", summary="إنشاء عنصر", description="إنشاء عنصر مع اسم ووصف وسعر وضريبة.")
def create_item(item: Item):
    return item

أوصاف الاستجابة

يمكنك تحديد الأوصاف لرموز الحالة الاستجابة المختلفة.

from fastapi import HTTPException

@app.get("/items/{item_id}", response_description="العنصر المسترجع")
def read_item(item_id: int):
    if item_id not in items:
        raise HTTPException(status_code=404, detail="العنصر غير موجود")
    return {"item_id": item_id}

دمج FastAPI مع Apidog

الآن بعد أن أصبحت على دراية بـ FastAPI وميزاته الوثائقية، دعنا نتحدث عن كيفية Apidog يمكن أن تعزز تجربة تطوير API الخاصة بك. Apidog هي أداة إدارة API شاملة تبسط عملية تصميم واختبار وإدارة APIs الخاصة بك.

كيفية إنشاء وثائق API قياسية تلقائيًا

الخطوة 1: التسجيل في Apidog

لتبدأ باستخدام Apidog لتوليد وثائق API، ستحتاج إلى التسجيل للحصول على حساب إذا لم تقم بذلك بالفعل. بمجرد تسجيل الدخول، ستستقبل واجهة Apidog سهلة الاستخدام.

الخطوة 2: إنشاء طلب API الخاص بك

يتكون مشروع وثائق API من نقاط النهاية المختلفة، حيث يمثل كل منها مسار API أو وظيفة معينة. لإضافة نقطة نهاية، انقر على زر "+" أو "API جديدة" داخل مشروعك.

الخطوة 3: إعداد معلمات الطلب

ستحتاج إلى تقديم تفاصيل مثل عنوان URL لنقطة النهاية، والوصف، وتفاصيل الطلب/الاستجابة. والآن تأتي المرحلة الحاسمة – توثيق نقاط النهاية الخاصة بك. تجعل Apidog هذه العملية مباشرة للغاية. بالنسبة لكل نقطة نهاية، يمكنك:

• تحديد طريقة HTTP (GET، POST، PUT، DELETE، إلخ).
• تحديد معلمات الطلب، بما في ذلك أسمائها وأنواعها وأوصافها.
• وصف الاستجابة المتوقعة، بما في ذلك رموز الحالة، وصيغ الاستجابة (JSON، XML، إلخ)، وأمثلة الاستجابة.

كثير من المطورين لا يحبون كتابة وثائق API، وغالبًا ما يجدونها معقدة. ومع ذلك، في الواقع، مع Apidog، يمكنك إكمالها ببضع نقرات فقط. واجهة Apidog المرئية صديقة للمبتدئين، مما يجعلها أبسط بكثير من توليد وثائق API من الكود.

الخطوة 4. توليد API الخاص بك

عندما تكمل معلومات API الأساسية، ما عليك سوى نقرة واحدة للحفظ كحالة. يمكنك أيضًا حفظها مباشرة، ولكن يُوصى بحفظها كحالة اختبار لسهولة الرجوع إليها في المستقبل.

في الختام، فإن اتباع هذه الخطوات الأربع يمكّنك من توليد وثائق API قياسية بسهولة. تساعد هذه العملية المبسطة في ضمان الوضوح والتناسق وتوفير الوقت الثمين. مع الوثائق التلقائية، ستكون مجهزًا جيدًا لتعزيز التعاون، وتبسيط تفاعل المستخدم، ودفع مشاريعك قدمًا بثقة.

توليد الوثائق للطلبات في Apidog

يدعم Apidog توليد وثائق API لمطوري API بناءً على ما قاموا به في مشاريعهم.

للشروع، أولاً، ابحث عن زر "مشاركة" كما أشار السهم 1، واضغط على زر "+ جديد" كما أشار السهم 2.

يوفر Apidog خيارًا لاختيار من يمكنه عرض وثائق API الخاصة بك وكذلك تعيين كلمة مرور للملف، لذا يمكن فقط للأفراد أو المنظمات المختارة عرضها.

بمجرد ملء جميع الحقول المطلوبة مثل اسم وثائق API واللغة، اضغط على Enter على لوحة المفاتيح الخاصة بك أو زر حفظ.

عرض أو مشاركة وثائق API الخاصة بك

يجمع Apidog تفاصيل مشروع API الخاص بك في وثائق API يمكن عرضها من خلال عنوان URL لموقع ويب. كل ما عليك فعله هو النقر على رابط نسخ الرابط تحت الإجراءات، ولصق عنوان URL على متصفحك المفضل لعرض وثائق API الخاصة بك!

تصميم API الخاص بك

مع Apidog، يمكنك تصميم نقاط النهاية الخاصة بك بصريًا، وتحديد المعلمات، وتحديد مخططات الطلب/الاستجابة. تسهل هذه approach البصرية إنشاء تصميم API واضح وموجز.

اختبار API الخاص بك

يوفر Apidog إمكانيات اختبار قوية تتيح لك اختبار نقاط نهاية API الخاصة بك مباشرة داخل الأداة. يمكنك إنشاء حالات اختبار، وتشغيلها، وعرض النتائج، كل ذلك في مكان واحد.

إدارة API الخاص بك

يقدم Apidog أيضًا ميزات لإدارة API الخاصة بك، مثل النسخ، والتحكم في الوصول، وتحليلات الاستخدام. تساعد هذه الميزات في تتبع أداء API لديك وضمان بقائها آمنة ومحدثة.

الخاتمة

يعد FastAPI خيارًا ممتازًا لبناء APIs عالية الأداء باستخدام Python. إن سهولة استخدامه، والوثائق الآلية، والميزات القوية تجعله مفضلًا بين المطورين. من خلال اتباع أفضل الممارسات للوثائق واستغلال أدوات مثل Apidog، يمكنك إنشاء APIs قوية وسهلة الاستخدام تلبي احتياجاتك.

فماذا تنتظر؟ ابدأ في بناء API التالي الخاص بك باستخدام FastAPI وحسّن من عملية التطوير الخاصة بك مع Apidog. قم بتحميل Apidog مجانًا اليوم وانتقل بتطوير API الخاص بك إلى المستوى التالي!