كيفية بناء وتوثيق واجهات برمجة التطبيقات RESTful باستخدام Flask-RESTX و Apidog

بناء واجهات برمجة التطبيقات RESTful هو مهارة أساسية لتطوير الويب الحديث، مما يمكن من التواصل السلس بين العملاء والخوادم. Flask-RESTX، هو إضافة لإطار العمل الشهير Flask، يسهل هذه العملية من خلال توفير أدوات لإنشاء واجهات برمجة التطبيقات القوية بكفاءة. في هذا الدليل، سنستكشف كيفية بناء واجهة برمجة تطبيقات RESTful باستخدام Flask-RESTX وسنوضح كيفية اختبارها باستخدام Apidog، وهي منصة متكاملة لـ تصميم واجهة برمجة التطبيقات، تصحيح الأخطاء، التوثيق، التقليد، و اختبار.

1. مقدمة في واجهات برمجة التطبيقات RESTful

REST (نقل الحالة التمثيلية) هو نمط معماري يستخدم طرق HTTP القياسية للتفاعل مع الموارد. يتم تصنيف واجهات برمجة التطبيقات التي تتبع مبادئ REST على أنها واجهات برمجة التطبيقات RESTful. توفر واجهات برمجة التطبيقات واجهة متوقعة وموحدة للتفاعلات بين العميل والخادم، مما يجعل خدمات الويب أكثر سهولة وصيانة.

2. إعداد بيئة التطوير الخاصة بك

قبل أن نبدأ في بناء واجهة برمجة التطبيقات الخاصة بنا، دعنا نعد بيئة التطوير الخاصة بنا.

المتطلبات الأساسية

Python 3.7 أو أعلى: تأكد من تثبيت Python على نظامك. تحقق عن طريق تشغيل:

python --version

البيئة الافتراضية: من الجيد إنشاء بيئة افتراضية لمشروعك لإدارة التبعيات.

python -m venv venv
source venv/bin/activate  # على Windows: venv\Scripts\activate

تثبيت Flask و Flask-RESTX

مع تفعيل البيئة الافتراضية، قم بتثبيت Flask و Flask-RESTX باستخدام pip:

pip install flask flask-restx

تقوم هذه الأداة بتثبيت كل من Flask و Flask-RESTX، مما يسمح لنا بإنشاء وإدارة نقاط نهاية واجهة برمجة التطبيقات بفعالية.

3. تثبيت وتكوين Flask-RESTX

Flask-RESTX هو إضافة تضيف الدعم لبناء واجهات REST بسرعة مع Flask. تشجع على أفضل الممارسات مع الحد الأدنى من الإعداد.

التثبيت

إذا لم تقم بتثبيت Flask-RESTX بعد، يمكنك القيام بذلك باستخدام pip:

pip install flask-restx

التكوين

قم بإنشاء ملف Python جديد، على سبيل المثال app.py، وقم بإعداد التكوين الأساسي:

from flask import Flask
from flask_restx import Api

app = Flask(__name__)
api = Api(app, version='1.0', title='واجهة برمجة التطبيقات النموذجية',
          description='واجهة برمجة تطبيقات نموذجية باستخدام Flask-RESTX')

if __name__ == '__main__':
    app.run(debug=True)

يقوم هذا السكربت بتهيئة تطبيق Flask ويغلفه مع مثيل واجهة برمجة التطبيقات Flask-RESTX، مما يوفر أساسًا لبناء نقاط النهاية.

4. إنشاء أول نقطة نهاية لواجهة برمجة التطبيقات الخاصة بك

دعنا ننشئ نقطة نهاية بسيطة لفهم كيفية عمل Flask-RESTX.

تحديد مساحة اسم

تساعد المساحات في Flask-RESTX في تنظيم واجهتك ومنع تصادم أسماء نقاط النهاية.

from flask_restx import Namespace, Resource

ns = Namespace('hello', description='عمليات مرحبا بالعالم')

إنشاء مورد

الموارد في Flask-RESTX تتوافق مع نقاط النهاية وتحدد كيفية التعامل مع طرق HTTP.

@ns.route('/')
class HelloWorld(Resource):
    def get(self):
        return {'message': 'مرحبًا، العالم!'}

تسجيل مساحة الاسم

أخيرًا، قم بتسجيل مساحة الاسم مع واجهة برمجة التطبيقات:

api.add_namespace(ns)

الآن، عندما تقوم بتشغيل تطبيقك والتنقل إلى http://localhost:5000/hello/، يجب أن ترى:

{
  "message": "مرحبًا، العالم!"
}

5. هيكلة تطبيق Flask-RESTX الخاص بك

مع نمو تطبيقك، من الضروري الحفاظ على هيكل نظيف ومنظم.

البنية الموصى بها للمشروع

project/
├── app/
│   ├── __init__.py
│   ├── controllers/
│   │   ├── __init__.py
│   │   └── hello_controller.py
│   ├── models/
│   │   ├── __init__.py
│   │   └── hello_model.py
│   └── services/
│       ├── __init__.py
│       └── hello_service.py
├── run.py
└── requirements.txt

تهيئة التطبيق

في app/__init__.py:

from flask import Flask
from flask_restx import Api

def create_app():
    app = Flask(__name__)
    api = Api(app, version='1.0', title='واجهة برمجة تطبيقات نموذجية',
              description='واجهة برمجة تطبيقات نموذجية باستخدام Flask-RESTX')

    from .controllers.hello_controller import ns as hello_namespace
    api.add_namespace(hello_namespace)

    return app

في run.py:

from app import create_app

app = create_app()

if __name__ == '__main__':
    app.run(debug=True)

تناقش هذه الطريقة النمطية الفصول، مما يجعل التطبيق أكثر سهولة في الصيانة والتطوير.

6. تنفيذ عمليات CRUD

عمليات CRUD—إنشاء، قراءة، تحديث، حذف—أساسية لتطوير واجهة برمجة التطبيقات. دعنا ننفذ هذه العمليات لمورد بسيط Item.

تحديد النموذج

في app/models/item_model.py:

from flask_restx import fields

def get_item_model(api):
    return api.model('Item', {
        'id': fields.Integer(readOnly=True, description='المعرف الفريد للعنصر'),
        'name': fields.String(required=True, description='اسم العنصر'),
        'price': fields.Float(required=True, description='سعر العنصر')
    })

تنفيذ المورد

في app/controllers/item_controller.py:

from flask_restx import Namespace, Resource, reqparse
from app.models.item_model import get_item_model

ns = Namespace('items', description='عمليات العنصر')

item_model = get_item_model(ns)

items = []
item_id_counter = 1

parser = reqparse.RequestParser()
parser.add_argument('name', type=str, required=True, help='اسم العنصر')
parser.add_argument('price', type=float, required=True, help='سعر العنصر')

@ns.route('/')
class ItemList(Resource):
    @ns.marshal_list_with(item_model)
    def get(self):
        return items

    @ns.expect(item_model)
    @ns.marshal_with(item_model, code=201)
    def post(self):
        global item_id_counter
        args = parser.parse_args()
        item = {
            'id': item_id_counter,
            'name': args['name'],
            'price': args['price']
        }
        items.append(item)
        item_id_counter += 1
        return item, 201

@ns.route('/<int:id>')
@ns.response(404, 'العنصر غير موجود')
@ns.param('id', 'معرف العنصر')
class Item(Resource):
    @ns.marshal_with(item_model)
    def get(self, id):
        item = next((item for item in items if item['id'] == id), None)
        إذا كان العنصر ليس None:
            return item
        ns.abort(404, message="العنصر غير موجود")

    @ns.expect(item_model)
    @ns.marshal_with(item_model)
    def put(self, id):
        item = next((item for item in items if item['id'] == id), None)
        إذا كان العنصر ليس None:
            args = parser.parse_args()
            item.update({
                'name': args['name'],
                'price': args['price']
            })
            return item
        ns.abort(404, message="العنصر غير موجود")

    @ns.response(204, 'تم حذف العنصر')
    def delete(self, id):
        global items
        item = next((item for item in items if item['id'] == id), None)
        إذا كان العنصر ليس None:
            items = [item for item in items if item['id'] != id]
            return '', 204
        ns.abort(404, message="العنصر غير موجود")

في هذا التنفيذ:

• GET /items/:retrieve قائمة العناصر.
• POST /items/: يضيف عنصرًا جديدًا.
• GET /items/{id}: استرجاع عنصر محدد بواسطة المعرف.
• PUT /items/{id}: تحديث عنصر موجود بواسطة المعرف.
• DELETE /items/{id}: حذف عنصر بواسطة المعرف.

يوفر هذا الإعداد واجهة CRUD كاملة لإدارة العناصر في واجهة برمجة التطبيقات الخاصة بك.

7. التحقق من صحة البيانات وتنسيقها باستخدام Flask-RESTX

التحقق من صحة البيانات والتسلسل ضروريان لضمان سلامة البيانات وتوافقها التي تقوم واجهة برمجة التطبيقات بمعالجتها. يقدم Flask-RESTX زخارف وحقول لتسهيل ذلك.

استخدام النماذج للتحقق من الصحة

حدد نموذجًا لتحديد تنسيقات الإدخال والإخراج المتوقعة.

from flask_restx import fields

item_model = api.model('Item', {
    'id': fields.Integer(readOnly=True, description='المعرف الفريد للعنصر'),
    'name': fields.String(required=True, description='اسم العنصر'),
    'price': fields.Float(required=True, description='سعر العنصر')
})

من خلال تزيين طرق المورد الخاصة بك باستخدام @ns.expect(item_model)، سوف يتحقق Flask-RESTX تلقائيًا من بيانات JSON الواردة مقابل هذا النموذج.

تسلسل الاستجابات

استخدم الديكور @ns.marshal_with لتنسيق الإخراج وفقًا للنموذج.

@ns.marshal_with(item_model)
def get(self, id):
    # استرجع وارجع العنصر

هذا يضمن أن بيانات الاستجابة تتماشى مع الهيكل المحدد، مما يعزز التناسق عبر واجهة برمجة التطبيقات الخاصة بك.

8. اختبار واجهات برمجة التطبيقات RESTful باستخدام Apidog

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

إعداد Apidog

التحميل والتثبيت: قم بتحميل Apidog مجانًا واتبع تعليمات التثبيت لنظام التشغيل الخاص بك.

إنشاء مشروع جديد: قم بتشغيل Apidog وأنشئ مشروعًا جديدًا لواجهة برمجة التطبيقات الخاصة بك.

استيراد مواصفات واجهة برمجة التطبيقات الخاصة بك

إذا كنت قد وثقت واجهة برمجة التطبيقات الخاصة بك باستخدام OpenAPI/Swagger، يمكنك استيراد المواصفة إلى Apidog:

استيراد المواصفة: في مشروعك على Apidog، اختر الخيار لاستيراد مواصفة واجهة برمجة التطبيقات وقم بتحميل ملف OpenAPI الخاص بك.

استكشاف نقاط النهاية: سيقوم Apidog بتحليل الملف وعرض نقاط نهاية واجهة برمجة التطبيقات الخاصة بك، والمعلمات، والنماذج.

يمكنك أيضًا تصميم واجهات برمجة التطبيقات من الصفر في Apidog.

اختبار نقاط النهاية

اختيار نقطة نهاية: اختر نقطة النهاية التي ترغب في اختبارها من القائمة.

تكوين الطلب:

• الطريقة: تأكد من تحديد طريقة HTTP الصحيحة (GET، POST، PUT، DELETE).
• المعلمات: أدخل أي معلمات استعلام أو متغيرات مسار مطلوبة.
• الرؤوس: قم بتعيين الرؤوس الضرورية، مثل Content-Type: application/json.
• الجسم: بالنسبة لطلبات POST و PUT، قم بتوفير payload JSON.

إرسال الطلب: انقر على زر إرسال لتنفيذ الطلب.

مراجعة الاستجابة:

(نصيحة احترافية: يغ validates Apidog استجابة واجهة برمجة التطبيقات تلقائيًا.)

• رمز الحالة: تحقق من أن رمز الحالة في الاستجابة يتطابق مع التوقعات (على سبيل المثال، 200 للنجاح، 201 لإنشاء).
• جسم الاستجابة: تحقق من أن البيانات المعادة صحيحة ومformatted بشكل صحيح.
• الرؤوس: افحص رؤوس الاستجابة للحصول على معلومات إضافية.

9. إنشاء وثائق واجهة برمجة التطبيقات باستخدام Flask-RESTX

تعد الوثائق الشاملة أمرًا ضروريًا لأي واجهة برمجة التطبيقات، مما يسهل الاستخدام والتكامل للمطورين. يوفر Flask-RESTX دعمًا مدمجًا لإنشاء وثائق تفاعلية لواجهة برمجة التطبيقات.

تعد الوثائق الشاملة وسهلة الاستخدام مسألة مهمة للمطورين والمستخدمين الذين يتفاعلون مع واجهة برمجة التطبيقات الخاصة بك. يبسط Flask-RESTX هذه العملية من خلال إنشاء وثائق واجهة برمجة التطبيقات في واجهة Swagger UI تلقائيًا، مما يوفر واجهة تفاعلية لاستكشاف واختبار نقاط نهاية واجهة برمجة التطبيقات الخاصة بك.

وثائق Swagger تلقائية

بشكل افتراضي، يقوم Flask-RESTX بإنشاء وثائق Swagger يمكن الوصول إليها على عنوان URL الجذري لواجهة برمجة التطبيقات الخاصة بك. توفر هذه الميزة نظرة عامة فورية على بنية واجهة برمجة التطبيقات الخاصة بك ونقاط النهاية المتاحة دون الحاجة إلى تكوين إضافي.

تخصيص الوثائق باستخدام الزخارف

يوفر Flask-RESTX العديد من الزخارف لتعزيز وتخصيص وثائق واجهة برمجة التطبيقات الخاصة بك:

@api.doc(): يضيف معلومات إضافية إلى الموارد أو الطرق لديك، على سبيل المثال، لتوثيق المعلمات:

@api.route('/my-resource/<id>')
@api.doc(params={'id': 'معرف'})
class MyResource(Resource):
    def get(self, id):
        return {}

@api.response(): يوثق الاستجابات المتوقعة، بما في ذلك رموز الحالة والأوصاف:

@api.route('/my-resource/<id>')
class MyResource(Resource):
    @api.response(403, 'غير مصرح')
    def post(self, id):
        api.abort(403)

@api.marshal_with(): يحدد النموذج الناتج للاستجابة، مما يضمن تنسيق بيانات متسق:

@api.route('/item/<int:id>')
class ItemResource(Resource):
    @api.marshal_with(item_model)
    def get(self, id):
        # استرجع وارجع العنصر

@api.expect(): يحدد النموذج المدخل المتوقع للطلبات، مما يسهل التحقق من الصحة والتوثيق:

@api.route('/item')
class ItemResource(Resource):
    @api.expect(item_model)
    def post(self):
        # التعامل مع طلب النشر

تنظيم باستخدام المساحات

تساعد المساحات في Flask-RESTX في تجميع الموارد ذات الصلة، مما يعزز تنظيم واجهة برمجة التطبيقات الخاصة بك ووثائقها.

from flask_restx import Namespace, Resource

ns = Namespace('items', description='عمليات العنصر')

@ns.route('/<int:id>')
class ItemResource(Resource):
    def get(self, id):
        # استرجع وارجع العنصر

من خلال تسجيل مساحة الاسم مع واجهة برمجة التطبيقات، يتم تجميع جميع المسارات والوصف المرتبطة بشكل مناسب:

api.add_namespace(ns)

الوصول إلى واجهة Swagger UI

بمجرد تشغيل تطبيق Flask-RESTX الخاص بك، يمكنك الوصول إلى واجهة Swagger UI التي تم إنشاؤها تلقائيًا من خلال الانتقال إلى عنوان URL الجذري لواجهة برمجة التطبيقات الخاصة بك (على سبيل المثال، http://localhost:5000/). توفر هذه الواجهة استكشافًا تفاعليًا لواجهة برمجة التطبيقات الخاصة بك، تعرض نقاط النهاية المتاحة، والمدخلات المتوقعة، والاستجابات المحتملة.

من خلال الاستفادة من هذه الميزات، تضمن أن واجهة برمجة التطبيقات الخاصة بك موثقة جيدًا، وسهلة الاستخدام، وسهلة الفهم للمطورين والمستخدمين على حد سواء.

10. تعزيز وثائق واجهة برمجة التطبيقات باستخدام Apidog

بينما يوفر Flask-RESTX الوثائق الأساسية، يقدم Apidog ميزات متقدمة لـ وثائق واجهة برمجة التطبيقات، بما في ذلك التخصيص، توليد الأكواد التلقائية، والاختبار في الوقت الحقيقي.

استخدم محرر Apidog المرئي لتعريف نقاط النهاية لواجهة برمجة التطبيقات، والمعلمات، وschemas الاستجابة. مع نقرة واحدة، يمكنك إنشاء وثائق واجهة برمجة تطبيقات شاملة وتفاعلية.

شارك وثائقك مع أعضاء الفريق أو الشركاء الخارجيين، مما يسمح لهم باختبار نقاط النهاية لواجهة برمجة التطبيقات مباشرة ضمن الوثائق.

من خلال دمج Flask-RESTX مع Apidog، يمكنك إنشاء واجهات برمجة تطبيقات قوية مع وثائق ذات جودة احترافية، مما يعزز كل من كفاءة التطوير وتجربة المستخدم.

الخاتمة

في هذا الدليل الشامل، استكشفنا عملية بناء واجهات برمجة التطبيقات RESTful باستخدام Flask-RESTX، وهو امتداد قوي لـ Flask يبسط تطوير واجهات برمجة التطبيقات. عالجنا مواضيع أساسية مثل إعداد بيئة التطوير الخاصة بك، وإنشاء وإدارة نقاط نهاية واجهة برمجة التطبيقات، والتحقق من صحة البيانات وتسلسلها، وإنشاء وثائق واجهة برمجة التطبيقات التفاعلية.

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