الدليل: إنشاء وثائق API REST باستخدام ستوبلايت ستوديو

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

ما هو ستوبلايت ستوديو؟

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

الميزات الرئيسية لستوبلايت ستوديو

أدوات الاختبار: يحتوي ستوبلايت ستوديو على ميزات اختبار تسمح للمطورين باختبار نقاط نهاية واجهة برمجة التطبيقات داخل المحرر.

مولد التوثيق: يحتوي ستوبلايت ستوديو على مولد توثيق واجهة برمجة التطبيقات مدمج. وهذا يسمح للتوثيق بالبقاء متزامنًا مع تنفيذ واجهة برمجة التطبيقات الفعلي.

معايير الصناعة: يدعم ستوبلايت ستوديو معايير الصناعة وأفضل الممارسات. عليك أن تتأكد فقط من أن جودة واجهة برمجة التطبيقات التي تقوم بتصميمها من الدرجة الأولى!

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

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

يمكن لمستخدمي ستوبلايت ستوديو الاعتماد بثقة على التطبيق لإنشاء تصاميم وتوثيقات رائعة لواجهة برمجة التطبيقات!

دليل خطوة بخطوة لتصميم واجهة برمجة التطبيقات وإنشاء توثيق REST API مع ستوبلايت ستوديو

دعنا ننتقل مباشرة إلى جوهر هذه المقالة: كيف يمكنك بالضبط إنشاء توثيق REST API باستخدام ستوبلايت ستوديو؟

الخطوة 1 - الاشتراك وتسجيل الدخول إلى ستوبلايت ستوديو

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

توقع أنك ستحتاج إلى تسجيل الدخول وإنشاء مساحة العمل الخاصة بك.

الخطوة 2 - إنشاء مشروع جديد

بعد أن تقوم بإعداد ستوبلايت ستوديو بنجاح، سيتم توجيهك إلى صفحة لوحة القيادة الخاصة بك على ستوبلايت ستوديو.

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

الخطوة 3 - إعداد تفاصيل المشروع الجديد

ستطلب منك ستوبلايت ستوديو إعداد اسم مشروع واجهة برمجة التطبيقات. قد تلاحظ أنه يوجد شعار يقول "لديك حالياً مشروع واحد متاح". في الوقت الحالي، تجاهل هذا أولاً.

الخطوة 4 - إنشاء توثيق واجهة برمجة التطبيقات داخل مشروع واجهة برمجة التطبيقات

على الشاشة الخاصة بك، اختر الزر API الموجود تحت قسم "إنشاء". يجب أن يكون هناك رمز سحابي وردي/أرجواني على هذا الزر.

الخطوة 5 - إعداد تفاصيل واجهة برمجة التطبيقات الجديدة

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

هنا، يمكنك أن تقرر إذا كنت ترغب في استيراد واجهات برمجة التطبيقات OpenAPI أو Postman الحالية.

الخطوة 6 - تحديد نقطة نهاية واجهة برمجة التطبيقات والتفاصيل

قم بتضمين أكبر عدد ممكن من التفاصيل حول واجهة برمجة التطبيقات. يتضمن ذلك المعلمات، وطلبات، وتفاصيل الاستجابة. يمكنك إضافة التفاصيل عن طريق تغيير علامات التبويب كما هو موضح بالسهم 1.

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

الخطوة 7 - نشر توثيق واجهة برمجة التطبيقات في ستوبلايت ستوديو

بمجرد أن تكمل تصميم واجهة برمجة التطبيقات الخاصة بك على ستوبلايت ستوديو، اضغط على زر + نشر كما هو موضح بالسهم 1 في الصورة أدناه:

ثم، اضغط على زر <- الذهاب إلى المستندات كما هو موضح بالسهم 2 لرؤية توثيق واجهة برمجة التطبيقات التي تم إنشاؤها. يجب أن يقودك إلى صفحة تبدو مثل هذه:

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

عيوب ستوبلايت ستوديو

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

• نقص تنوع لغة العميل: قد تكون قد لاحظت أن ستوبلايت ستوديو يفتقر إلى تنوع لغات العميل. قد يكون هذا غير مفيد للمطورين الذين يستخدمون لغات برمجة أقل شهرة ولكن لا تزال ذات صلة.
• نقص وظائف الاختبار: ستوبلايت ستوديو هو أداة ممتازة للتصميم والتوثيق لخدمات الويب، ولكنه لا يملك وظائف الاختبار الأساسية لتصحيح واجهات برمجة التطبيقات.
• يعتمد على السحاب / الإنترنت: يتم تخزين تصميم توثيق واجهة برمجة التطبيقات جميعها في السحابة، مما يجعل العمل بدون اتصال صعبًا. وهذا يعني أيضًا أن انقطاع الاتصال بالإنترنت قد يؤدي إلى تعطيل تدفق العمل.
• منحنى التعلم الحاد: قد يبدو سهل الاستخدام في البداية، ومع ذلك، ذكر مطورون آخرون أن الميزات المتقدمة التي يقدمها ستوبلايت ستوديو قد تتطلب مزيدًا من الوقت لفهم.

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

Apidog: الحل الشامل لعمليات دورة حياة واجهة برمجة التطبيقات الكاملة

Apidog هو أداة واجهة برمجة التطبيقات التي تؤسس واجهة مستخدم بسيطة وأنيقة مثل ستوبلايت ستوديو. باستخدام واجهة الرسوميات، يمكن للمستخدمين تصور كل عملية في دورة حياة واجهة برمجة التطبيقات - التصميم، التوثيق، واختبار واجهات برمجة التطبيقات دون الحاجة إلى برمجة YAML أو JSON.

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

ما يميز Apidog عن ستوبلايت ستوديو هو أن Apidog لديه العديد من ميزات الاختبار التي تقدمها، بدءًا من اختبار الوحدة إلى اختبار السيناريو.

تصميم واجهات برمجة التطبيقات مع Apidog

قبل كل مرحلة من مراحل اختبار المنتج، هناك عملية تصميم. مع Apidog. يمكنك تصميم واجهات برمجة التطبيقات مع مواصفات OpenAPI، وإنشاء التوثيق المتعلق بها في بضع نقرات فقط.

تكوين طرق ونقاط نهاية واجهة برمجة التطبيقات

السهم 1 - تأكد من صحة عنوان URL الصحيحة لطلبك. تأكد من أنه لا يوجد به أخطاء إملائية حتى تتمكن من الحصول على استجابة!

السهم 2 - قرر ما هي طريقة واجهة برمجة التطبيقات التي ترغب بها. الطرق الأكثر شيوعًا هي GET و POST و PUT و DELETE تحديدًا. ومع ذلك، يوفر Apidog خيارات لاختيار OPTIONS و HEAD و PATCH.

السهم 3 - اشرح تفاصيل واجهة برمجة التطبيقات بدقة من خلال تضمين معلمات الطلب، معلمات الاستجابة، ونماذج الاستجابة أدناه. يُنصح بشدة بملء كل شيء حيث سيتم تضمين كل متغير في توثيق واجهة برمجة التطبيقات.

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

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

السهم 1 - اختر الطلب الذي ترغب في اختباره.

السهم 2- أرسل الطلب للحصول على استجابة. قبل الضغط على زر إرسال، تأكد من صحة نوع الطريقة والرابط.

السهم 3 - قم بتحليل الاستجابة لمعرفة ما إذا كانت تلبي متطلباتك أو توقعاتك للخدمة عبر الإنترنت.

إنشاء سيناريوهات اختبار لواجهات برمجة التطبيقات مع Apidog

سيناريوهات الاختبار هي سلسلة من الخطوات التي يمكنك تصميمها لخدمة الويب الخاصة بك لمحاكاة في حالة عملية. إليك دليل خطوة بخطوة حول كيفية البدء.

السهم 1 - حدد زر "الاختبار".

السهم 2 - اضغط على زر + سيناريو اختبار جديد.

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

أضف خطوة (أو المزيد من الخطوات) إلى سيناريوهات الاختبار الخاصة بك عن طريق النقر على قسم "إضافة خطوة". يجب أن تكون قادرًا على رؤية الصورة أدناه.

اختر "استيراد من واجهة برمجة التطبيقات" من القائمة المنسدلة.

اختر جميع واجهات برمجة التطبيقات التي ترغب في تضمينها في سيناريو الاختبار الخاص بك. في المثال أعلاه، تم تضمين واجهة برمجة التطبيقات المسماة NumberConversionSOAP.

السهم 1 - قم بتغيير سيناريو الاختبار إلى "بيئة اختبار".

السهم 2 - اضغط على تشغيل عندما يتم الانتهاء من كل التفاصيل.

إنشاء توثيق واجهة برمجة التطبيقات باستخدام Apidog

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

قم بالتسجيل باستخدام حساب تفضله لبدء استخدام Apidog. يمكنك استخدام حساب Gmail أو أي حساب بريد إلكتروني آخر للتسجيل، أو إذا كنت تفضل استخدام حساب GitHub الخاص بك، فلا تتردد، يرجى القيام بذلك.

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

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

تأكد من أنك قد حفظت جميع تقدمك في تطوير واجهة برمجة التطبيقات.

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

السهم 1 - ابدأ بالبحث عن الضغط على زر "مشاركة"، الموجود في الشريط العمودي على الجانب الأيسر من نافذة تطبيق Apidog. يجب أن تكون قادرًا على رؤية صفحة "المستندات المشتركة"، والتي يجب أن تكون فارغة.

السهم 2 - اضغط على زر "+ جديد" تحت "لا توجد بيانات" لبدء إنشاء توثيق واجهة برمجة التطبيقات REST API الأولى لك.

حدد وادخل خصائص توثيق واجهة برمجة التطبيقات الهامة

تأكد من أنك قد قمت بتحديد أو ملء جميع الحقول وفقًا لمتطلباتك. بمجرد أن تتحقق، يمكنك الضغط على زر "إدخال" على لوحة المفاتيح الخاصة بك، أو زر "حفظ" الموجود في أسفل الشاشة الحالية.

عرض أو مشاركة توثيق REST API الخاص بك

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

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

الخاتمة

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

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

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