api-doc-generator
إنشاء توثيق OpenAPI 3.0 من الشيفرة المصدرية الخاصة بك
كتابة توثيق API يدويًا بطيئة وغالبًا ما تكون غير مكتملة. تنشئ هذه المهارة تلقائيًا مواصفات OpenAPI 3.0 وأمثلة الطلبات ومجموعات Postman مباشرةً من شيفرتك، بحيث يمتلك فريقك دائمًا توثيق API دقيقًا.
تنزيل ZIP المهارة
رفع في Claude
اذهب إلى Settings → Capabilities → Skills → Upload skill
فعّل وابدأ الاستخدام
موارد قابلة للقراءة بواسطة Agent
استخدم هذه الروابط عندما يحتاج AI Agent أو crawler أو script إلى سياق نظيف بدلاً من قراءة الصفحة كاملة.
اختبرها
استخدام "api-doc-generator". مسار Express: GET /users/:id يُرجع { id, name, email } بالحالة 200 أو 404
النتيجة المتوقعة:
YAML لـ OpenAPI 3.0 يوثق GET /users/{id} مع مخطط معامل المسار ومخطط استجابة ناجحة يتضمن id (integer) وname (string) وemail (string)، وتعريف استجابة خطأ 404
استخدام "api-doc-generator". نقطة نهاية POST /orders تقبل { productId, quantity, shippingAddress } وتُرجع { orderId, status, total }
النتيجة المتوقعة:
مخطط كامل لجسم الطلب مع الحقول المطلوبة، ومخطط استجابة يتضمن تفاصيل تأكيد الطلب، وإدخال مجموعة Postman جاهز للاستخدام مع حمولة JSON نموذجية
استخدام "api-doc-generator". أعد هيكلة توثيق API الداخلي هذا إلى مرجع OpenAPI موجّه للعامة
النتيجة المتوقعة:
مواصفة OpenAPI منقحة مع تعريفات مخطط الأمان، وتوثيق تحديد المعدل، وترويسات إدارة الإصدارات، وأوصاف نقاط النهاية المنسقة بصيغة Markdown والمناسبة لبوابة مطورين عامة
التدقيق الأمني
آمنTwo static analysis findings evaluated and dismissed as false positives. The 'weak cryptographic algorithm' alert on SKILL.md:4 is a YAML description field with no cryptography. The 'high file entropy' alert is caused by CJK/Chinese UTF-8 characters, which naturally have higher entropy than ASCII text. No actual security threats found: no network access, no filesystem operations, no external commands, no scripts, no environment variable access, and no prompt injection attempts detected.
الأنماط المكتشفة
درجة الجودة
ماذا يمكنك بناءه
إنشاء توثيق API تلقائيًا من شيفرة الواجهة الخلفية
يلصق مطورو الواجهة الخلفية معالجات المسارات أو ملفات وحدات التحكم الخاصة بهم ويحصلون على مستندات مواصفات OpenAPI 3.0 كاملة وجاهزة لاستخدام الفريق.
إنشاء مجموعات Postman للتأهيل
يحصل مطورو الواجهة الأمامية وأعضاء الفريق الجدد على مجموعات Postman جاهزة للاستيراد مع طلبات أمثلة حتى يتمكنوا من استكشاف واختبار واجهات API فورًا.
توحيد توثيق API عبر الفرق
يستخدم قادة الهندسة هذه المهارة لفرض توثيق OpenAPI متسق عبر الخدمات المصغرة، مما يضمن أن كل API يتبع تنسيق المواصفات نفسه.
جرّب هذه الموجهات
أنشئ توثيق API لمعالج مسار Express هذا. ضمّن طريقة HTTP والمسار ومعاملات الطلب وتنسيق الاستجابة.
أنشئ مواصفة YAML كاملة لـ OpenAPI 3.0 لوحدة تحكم REST API هذه. ضمّن جميع نقاط النهاية ومخططات الطلب ومخططات الاستجابة وأكواد الأخطاء.
أنشئ JSON لمجموعة Postman من تعريف API هذا. ضمّن ترويسات التفويض وأمثلة أجسام الطلبات ونصوص الاختبار لكل نقطة نهاية.
استخرج تعريفات API من هذه الملفات المصدرية المكتوبة بـ Python وJava وTypeScript. أنشئ مواصفة OpenAPI 3.0 موحدة بتسمية وأمثلة متسقة.
أفضل الممارسات
- قدّم ملفات شيفرة مصدرية كاملة تحتوي على جميع المسارات والمعالجات للحصول على مخرج توثيق أكثر شمولًا
- راجع دائمًا مواصفات OpenAPI المُنشأة للتأكد من صحتها وأضف أي تفاصيل منطق أعمال لا يمكن للشيفرة وحدها التعبير عنها
- ضمّن أمثلة لحمولات الطلبات وبيانات الاستجابة المتوقعة في مطالبتك لإنتاج توثيق API أكثر ثراءً
تجنب
- لا تلصق شيفرة مصدرية تحتوي على مفاتيح API أو رموز وصول أو أسرار عند طلب إنشاء التوثيق
- لا تنشر توثيق API المُنشأ دون مراجعة أوصاف نقاط النهاية والمخططات وتصحيحها أولًا
- تجنب توثيق نقاط النهاية الداخلية فقط أو المهملة التي لا ينبغي كشفها لمستهلكي API الخارجيين