أداة توثيق واجهة برمجة التطبيقات بالذكاء الاصطناعي

Trupeer هي أداة توثيق لواجهات برمجة التطبيقات (API) تعمل بالذكاء الاصطناعي، تحوّل سير عمل لواجهة برمجة التطبيقات تم تسجيله إلى دليل إرشادي بصري للمطوّرين. تلتقط التسلسل أثناء تنفيذك له، ثم تُنتج مستندًا خطوة بخطوة مع لقطات شاشة يمكنك تعديلها ونشرها.

يوثّق كيفية استخدام واجهة برمجة التطبيقات. لا يُعدّ مولّدًا لمواصفات OpenAPI ولا يستبدل أدوات التوثيق المرجعي، والتي يتم تناولها أدناه.

ما هي أداة توثيق واجهات برمجة التطبيقات (API) بالذكاء الاصطناعي؟

يشير المصطلح إلى أمرين مختلفين تمامًا، ومعرفة أيهما تحتاجه يوفر الكثير من وقت التقييم.

• توليد التوثيق المرجعي: يبني توثيق نقاط النهاية (endpoints) من مواصفة أو من كود. المسارات، الطرق، المعلمات، مخططات طلبات الاستعلام واستجاباتها، آليات المصادقة، وأكواد الأخطاء. غالبًا ما يعتمد على OpenAPI أو Swagger

• توثيق سير العمل: يوثّق كيفية استخدام شخص ما لواجهة برمجة التطبيقات فعليًا. المصادقة، إرسال طلب، قراءة الاستجابة، واستخدام النتيجة في المكالمة التالية. غالبًا ما يتم إنتاجه من تسجيل أو كتابته يدويًا

يقوم Trupeer بالأمر الثاني. إذا كنت تحتاج إلى الأول، فإن سلسلة أدوات OpenAPI هي الفئة المناسبة، وهذا ليس بديلاً عنها.

ما الذي يجب أن يتضمنه توثيق واجهة برمجة التطبيقات (API)؟

قد يغطي نظام توثيق واجهة برمجة التطبيقات (API) الكامل كلا الطبقتين. تتولى أدوات التوثيق المرجعي معظم القائمة الأولى؛ أما الطبقة الثانية فهي المكان الذي يثبت فيه توثيق سير العمل قيمته.

طبقة التوثيق المرجعي

• نقطة النهاية والطريقة والمسار

• المعلمات وجسم الطلب

• مخطط الاستجابة وأكواد الحالة

• آلية المصادقة

• أكواد الأخطاء ومعانيها

طبقة توثيق سير العمل

• البدء والإعداد: المفاتيح والبيئات والمتطلبات الأساسية

• ترتيب المكالمات التي تتم به، ولماذا

• كيف تبدو طلب واستجابة حقيقيان في الواقع

• كيف تغذي مخرجات مكالمة واحدة المكالمة التالية

• ما الذي يحدث خطأ في أغلب الأحيان، وما الذي يعنيه

يخبر التوثيق المرجعي المطوّر بما هو موجود. ويخبر توثيق سير العمل المطوّرين بكيفية جعل شيء ما يعمل. غالبًا ما تكون معظم واجهات برمجة التطبيقات موثقة جيدًا في الأولى وضعيفة في الثانية.

ما الذي يمكن لـ Trupeer إنشاؤه من سير عمل لواجهة برمجة التطبيقات (API)؟

• جولات توضيحية للتكامل: التسلسل من المصادقة إلى نتيجة تعمل، خطوة بخطوة

• أدلة البدء السريع: الإعداد والمفاتيح وتكوين البيئة كما يقوم بها الشخص فعليًا

• أدلة واجهات برمجة التطبيقات الداخلية: كيف يستخدم فريقك خدمة داخلية، بما في ذلك الأجزاء غير المكتوبة في أي مكان

• توثيق استكشاف الأخطاء وإصلاحها: الفشل الذي واجهه شخص ما وكيف تم حله، مع التقاطه أثناء حدوثه

• مواد الإعداد للمستخدمين الذين يستهلكون واجهة برمجة التطبيقات (API): دليل بصري إلى جانب أدلة المرجع لديك

كيف يعمل توثيق سير عمل واجهة برمجة التطبيقات (API)؟

الخطوة 1: سجّل أو ارفع سير عمل واجهة برمجة التطبيقات (API)

سجّل نفسك وأنت تعمل عبر واجهة برمجة التطبيقات باستخدام أي شيء تستخدمه. يلتقط المسجل علامة تبويب في المتصفح أو نافذة محددة أو كامل الشاشة، لذا تعمل أي عميل لواجهة برمجة التطبيقات أو طرفية (terminal) أو وحدة تحكم المتصفح. يمكنك أيضًا رفع تسجيل لديك بالفعل.

الخطوة 2: إنشاء الدليل

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

الخطوة 3: راجع وانشر

أضف التفسيرات التي لا يمكن للتسجيل حملها، وامسح/أزل المفاتيح والرموز التي ظهرت، ثم شارك الدليل أو صدّره إلى PDF أو Word.

مثال: توثيق تكامل لواجهة برمجة التطبيقات (API)

المدخلات: يقوم مطوّر بتسجيل نفسه وهو يقوم بالمصادقة وإرسال طلب وقراءة الاستجابة، ثم استخدام قيمة منها في مكالمة ثانية.

المخرجات: دليل يوضح هذا التسلسل بالترتيب، مع لقطة شاشة في كل خطوة. ثم يضيف المطوّر ما لم تُظهره الشاشة: أي الحقول المهمة في الاستجابة، وما هي حدود المعدل (rate limits)، وما الذي يعنيه الفشل الشائع.

ما ليس هو: مرجع لنقطة النهاية. لا يسرد كل معلمة ولا يولّد مخططًا. إنه يوثّق مسارًا واحدًا عبر واجهة برمجة التطبيقات، وهو ما يحتاجه القادمون الجدد أولاً.

توثيق سير العمل بالذكاء الاصطناعي مقابل توثيق OpenAPI

هذه مكملات وليست بدائل. فالتوثيق المرجعي بدون دليل بدء سريع يترك المطوّرين يقومون بتجميع التسلسل بأنفسهم؛ أما دليل بدون توثيق مرجعي فيتركهم عالقين بمجرد حاجتهم إلى معلمة لم تكن مغطاة.

متى يكمل توثيق سير العمل أدلة مرجع واجهة برمجة التطبيقات (API)؟

عند دمج مطوّر مع واجهة برمجة التطبيقات (API)، فإنه عادةً ما يحتاج إلى كليهما، في لحظات مختلفة.

• في البداية: دليل سير العمل. ماذا يجب إعداده، وأي مكالمة تأتي أولاً، وكيف يبدو التسلسل الذي يعمل من البداية إلى النهاية

• أثناء التنفيذ: المرجع. ما هي المعلمات التي تقبلها نقطة النهاية هذه، وما الذي يحتويه مخطط الاستجابة، وما أكواد الحالة التي تُرجعها

• عندما يتعطل شيء ما: كليهما. يخبرهم المرجع بما يعنيه كود الخطأ؛ ويخبرهم دليل سير العمل بمكان حدوثه عادةً ضمن التسلسل

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

إخفاء/حذف المفاتيح والرموز

يجدر التنبيه إلى ذلك، لأن سير عمل واجهات برمجة التطبيقات (API) يعرض بيانات الاعتماد على الشاشة أكثر من معظم العمليات. تظهر مفاتيح واجهة برمجة التطبيقات (API keys)، ورموز الحامل (bearer tokens)، ومعرّفات الحساب، وبيانات العملاء داخل أجسام الاستجابة في التسجيل وبالتالي في لقطات الشاشة.

يمكن قصّ لقطات الشاشة وتوضيحها (annotate) وإخفاءها/طمسها قبل نشر أي شيء، لذا يظل التسجيل الذي تم إجراؤه مقابل بيئة حقيقية قابلًا للاستخدام. إن القيام بذلك أثناء المراجعة بدلًا من محاولة تجنبه أثناء الالتقاط غالبًا ما يكون أكثر عملية، لكن تأكد من ذلك قبل مشاركة أي شيء خارجيًا.

ما الذي لا يفعله هذا

يساعد Trupeer في توثيق سير عمل واجهات برمجة التطبيقات (API) بصريًا. لا يقوم بتوليد مواصفات OpenAPI أو Swagger، ولا ينتج توثيقًا مرجعيًا لنقاط النهاية، ولا يسرد المعلمات أو المخططات، ولا يستبدل أدوات التوثيق المرجعي للمطوّرين.

كما أنه لا يمكنه توفير ما لم يكن ظاهرًا على الشاشة: لماذا تهم قيمة حقل معيّن، وما هي الحدود، أو ماذا يعني كود حالة معيّن في تطبيقك. تأتي هذه المعلومات من الشخص الذي كتب واجهة برمجة التطبيقات (API). للتحقق من مسودة تم توليدها، راجع دقة توثيق الذكاء الاصطناعي.

ولتوثيق سير عمل البرمجيات بشكل أوسع، راجع مولّد توثيق البرمجيات بالذكاء الاصطناعي.

وثّق سير عمل واجهة برمجة التطبيقات (API) التالي

سجّل التكامل مرة واحدة وحوّله إلى دليل يمكن لمطوّريك اتباعه. جرّب Trupeer مجانًا.