باستخدام مكون Apidog الإضافي لـ IDEA أو بعض مكونات Swagger الإضافية، يمكنك بسهولة إنشاء وثائق API من التعليمات البرمجية، مما يحل مشكلة كتابة الوثائق من الصفر.
ومع ذلك، حتى بعد كتابة نقاط النهاية وإنشاء الوثائق، قد تظل تشعر بعدم اليقين: هل تصميم API جيد بما فيه الكفاية؟ هل الوثائق موحدة؟ هل هناك مجالات يمكن تحسينها بشكل أكبر؟
خاصة في التعاون الجماعي، تريد أن تكون وثائق API الخاصة بك سهلة الفهم لزملائك في لمحة. وضوح التسمية واكتمال المعلومات يؤثران بشكل مباشر على تجربتهم في استخدام واجهات برمجة التطبيقات الخاصة بك.
طرح Apidog مؤخرًا العديد من ميزات الذكاء الاصطناعي لمساعدتك على تحسين وثائق API بشكل أكبر في هذه المرحلة. سواء كنت تقوم بتحسين تفاصيل نقطة نهاية موجودة أو استيراد وثائق API موجودة من مكان آخر، يمكن للذكاء الاصطناعي تقديم اقتراحات عملية.
أدناه، سنوضح كيفية استخدام الذكاء الاصطناعي في Apidog لإنشاء وثائق API أكثر توحيدًا. قبل أن نبدأ، يرجى التأكد من أنك قمت بتحديث Apidog إلى أحدث إصدار، وقمت بتمكين ميزات الذكاء الاصطناعي، وقمت بتكوين نموذج الذكاء الاصطناعي.
الاستيراد من الوثائق الموجودة
أحيانًا تحتاج إلى ترحيل وثائق API من مصادر أخرى إلى Apidog. إذا كانت الوثائق بتنسيق قياسي، فإن Apidog يدعم أصلاً طرق استيراد متعددة: يمكنك إنشاء وثائق من التعليمات البرمجية عبر مكون IDEA الإضافي، أو استيراد مواصفات OpenAPI/Swagger، أو الترحيل من أدوات أخرى مثل Postman.
ولكن في بعض الحالات، قد لا تكون وثائقك بتنسيقات قياسية. على سبيل المثال، قد يكون الفريق قد وثّق نقاط النهاية مسبقًا في Markdown، أو نظم أوصاف الحقول في Word، أو عثر على تعريفات نقاط النهاية في سجلات الدردشة أو رسائل البريد الإلكتروني. قد يكون إدخال كل حقل يدويًا من هذه المصادر غير القياسية إلى Apidog مهمة شاقة.
في هذه الحالة، يمكنك استخدام ميزة تعديل المخطط باستخدام الذكاء الاصطناعي للمساعدة في إدخال البيانات. افترض أن لديك محتوى Markdown مثل هذا:
| name | desc | type | required |
| ---------- | --------------------------------------------------------------------------- | --------- | -------- |
| usePaging | Whether to enable pagination | boolean | true |
| offset | Starting position (required when pagination is enabled) | int | false |
| pageSize | Number of items per page (required when pagination is enabled) | int | false |
| minPrice | Minimum price (unit: cents) | int | false |
| maxPrice | Maximum price (unit: cents) | int | false |
| brand | Brand code | string | false |
| categoryId | Product category ID | int | false |
| sortRule | Sorting rule: 1 → Sales priority, 2 → Price ascending, 3 → Price descending | enum(int) | false |
| keyword | Search keyword (fuzzy match on product name) | string | false |ما عليك سوى نسخ المعلمات وسؤال الذكاء الاصطناعي: "حوّل هذا المحتوى إلى معلمات نقطة نهاية، مع التأكد من تحديد الأنواع والحقول المطلوبة."
سيكتشف الذكاء الاصطناعي تلقائيًا أسماء الحقول وأنواع البيانات وحالة الإلزام والأوصاف، ثم يحول كل شيء إلى تنسيق مخطط Apidog القياسي. إذا كانت التعدادات (enums) مضمنة، فسوف يقوم الذكاء الاصطناعي أيضًا بتنظيمها في أنواع تعدادات مناسبة لك.
الذكاء الاصطناعي يساعدك على تحسين تفاصيل API
بعد استيراد المعلومات الأساسية، تتمثل الخطوة التالية في تحسين التفاصيل.
إذا كنت غير متأكد من اسم حقل ما، فاستخدم ميزة التسمية بالذكاء الاصطناعي. سيقدم الذكاء الاصطناعي اقتراحات تسمية أكثر دقة وفقًا لمواصفات نقطة النهاية وإرشادات تصميم API.
يمكنك أيضًا استخدام الذكاء الاصطناعي لإكمال أوصاف الحقول تلقائيًا للحصول على تفسيرات أوضح وأكثر اكتمالاً.
يعد إنشاء البيانات الوهمية (Mock data) إحدى نقاط قوة الذكاء الاصطناعي الأخرى. غالبًا ما نعرف ما يمثله الحقل ولكننا لسنا متأكدين من قيم الأمثلة التي يجب استخدامها. سيقوم الذكاء الاصطناعي تلقائيًا بإنشاء بيانات أمثلة معقولة بناءً على نوع الحقل ووصفه.
فحص اكتمال وثائق API: تجنب الإغفالات
عندما تبدو الوثائق شبه كاملة، قد تتساءل عما إذا كانت هناك أي معلومات أساسية مفقودة. في هذه المرحلة، استخدم فحص اكتمال وثائق API من Apidog لمعرفة ما إذا كان قد تم إغفال أي شيء.
سيقوم الذكاء الاصطناعي بفحص وثائق API الموجودة لديك من وجهات نظر متعددة لتحديد المعلومات المفقودة أو غير المكتملة. ثم يقوم بإنشاء تقرير مفصل يقيم كل عنصر مراجعة، مما يساعدك على رؤية المجالات التي تحتاج فيها وثائق API الخاصة بك إلى تحسين بسرعة.
التقرير لا يخبرك فقط بما يجب فعله، بل يشرح أيضًا السبب. على سبيل المثال، قد تكون قد وثّقت تنسيق استجابة ناجحًا ولكن ليس سيناريوهات الأخطاء المحتملة؛ قد تكون لديك أوصاف حقول أساسية ولكن تفتقر إلى قيود الاستخدام أو متطلبات التنسيق.
يمكنك تحسين وثائق API الخاصة بك باتباع الاقتراحات المقدمة في التقرير.
فحص توافق نقطة النهاية: ضمان الاتساق
إلى جانب كونها كاملة، تحتاج وثائق API أيضًا إلى أن تكون موحدة جيدًا. ضمن نقطة نهاية واحدة، يجب أن تتبع التسمية أسلوبًا متسقًا، ويجب تعريف أنواع الحقول بوضوح وصحة، ويجب أن تكون هياكل الاستجابة منطقية. تلعب هذه التفاصيل دورًا رئيسيًا في جعل وثائقك سهلة القراءة والصيانة.
تفحص ميزة فحص توافق نقطة النهاية في Apidog وثائقك من زوايا متعددة. على سبيل المثال، إذا كانت بعض الحقول مسماة بأفعال بينما تستخدم الأخرى أسماء، فسوف يشير الذكاء الاصطناعي إلى هذا التناقض ويوصي بأسلوب تسمية موحد.
كما تتحقق أيضًا مما إذا كانت تعريفات الحقول تتبع معايير متسقة، مثل تجنب أنماط الأحرف المختلطة، أو الاستخدام المتزامن للشرطات السفلية وcamelCase، أو الاختصارات غير المتسقة، ثم تقدم اقتراحات واضحة حول كيفية إصلاح هذه المشكلات.
ملخص
يعد إنشاء وثائق API واضحة وموحدة أمرًا ضروريًا. تعتمد الميزات مثل حالات الاختبار التي ينشئها الذكاء الاصطناعي على جودة وثائقك—كلما كانت أكثر اكتمالًا واتساقًا، كانت حالات الاختبار التي تم إنشاؤها أكثر دقة وفائدة.
لا تحتاج إلى استخدام كل ميزة من ميزات الذكاء الاصطناعي دفعة واحدة أو إعادة هيكلة سير عملك الحالي بالكامل.
هذه عملية تدريجية. يمكنك البدء باستيراد وثائقك الحالية ثم تطبيق ميزات الذكاء الاصطناعي ببطء لتحسينها وتنقيتها. إذا كنت غير متأكد من اقتراح ما، يمكنك ترك الأمور كما هي والعودة إليها لاحقًا عندما يكون لديك سياق أكبر.
مع مرور الوقت، ستكتسب بشكل طبيعي فهمًا أفضل لمعايير وثائق API. لا يساعد الذكاء الاصطناعي في حل المشكلات الفورية فحسب، بل يساعدك أيضًا على تطوير عادات توثيق أفضل.