عن المشروع

mitmproxy2swagger هي أداة سطر أوامر تحول تسجيلات حركة مرور HTTP (من ملفات تدفق mitmproxy أو ملفات HAR المُصدَّرة من أدوات مطوري المتصفح) إلى مواصفات OpenAPI 3.0 (Swagger). يتيح ذلك للمطورين هندسة REST APIs عكسيًا بسرعة بمجرد تشغيل تطبيق وتسجيل طلباته الشبكية، بدلاً من فحص نقاط النهاية والمعاملات يدويًا. ## القدرات الرئيسية - **صيغ الإدخال**: يقبل ملفات تدفق mitmproxy (`.mitm` عبر mitmweb/mitmproxy) وملفات HAR (يتم اكتشافها تلقائيًا). - **سير عمل من مرحلتين**: المرحلة الأولى تُنشئ قالبًا يحتوي على جميع المسارات المكتشفة؛ يقوم المستخدمون بتحرير القالب لاختيار نقاط النهاية التي سيتم تضمينها وضبط معاملات المسار (مثل استبدال المعرفات الديناميكية ببدائل `{id}`). المرحلة الثانية تملأ مخططات الطلبات/الاستجابات التفصيلية، وتجمع البيانات من جلسات التقاط متعددة دون الكتابة فوق المحتوى الموجود. - **مخططات قابلة للتوسيع**: يمكن دمج بيانات جديدة في ملف مخطط موجود، مما يسمح بالتحسين التدريجي عبر عمليات الالتقاط. - **إثراء البيانات الاختياري**: العلامات `--examples` و `--headers` تتضمن نماذج من الحمولات ومعلومات الترويسات (مع تحذير بشأن البيانات الحساسة المحتملة). - **صيغة الإخراج**: يُنشئ ملفات YAML متوافقة مع OpenAPI 3.0، قابلة للاستخدام مع أدوات التوثيق مثل Redoc. ## الاستخدام النموذجي 1. التقط حركة مرور HTTP (مثل استخدام `mitmweb`، ثم حفظ ملف التدفق). 2. شغّل `mitmproxy2swagger -i flow.mitm -o schema.yaml -p https://api.example.com/v1` لإنشاء القالب الأولي. 3. حرّر schema.yaml: أزل بادئات `ignore:` من المسارات المطلوبة. 4. أعد تشغيل الأمر لإنشاء تعريفات نقاط النهاية الكاملة. ## التفاصيل التقنية - مكتوب بلغة Python، يُثبَّت عبر pip أو يُشغَّل عبر Docker. - متاح على PyPI ومستودعات Arch Linux. - التطوير يستخدم uv وprek (للفحص) وpytest للاختبار؛ المساهمات مرحب بها. - مرخص بموجب MIT. ## حالة استخدام مثال بالنظر إلى تطبيق يرسل طلبات إلى `https://api.example.com/v1/login` و`/users/2` و`/users/2/profile`، ستقترح الأداة `https://api.example.com/v1` كبادئة، ثم توجه المستخدم لتعريف قوالب المسار مثل `/users/{id}` و`/users/{id}/profile`. للتجربة العملية، راجع دليل `example_outputs/` المرفق الذي يحتوي على مخطط مُنشأ وتوثيق HTML مُصيَّر.