تحدد سلامة وثائق API مدى فائدتها. استخدم الإجراءات القياسية عند كتابة وثائق REST APIs لإنشاء دليل يكون أكثر وضوحًا للقراءة والفهم لجميع القراء. دليل مرجعي سريع يغطي كل ما تحتاجه للتعرف على API ، بما في ذلك معلومات عن الإجراءات والفئات وأنواع النتائج والمعلمات والمزيد ، أصبح ممكنًا من خلال توثيق REST APIs. ستوجهك هذه المقالة إلى REST APIs ، وكيفية كتابة مستندات REST API ونصائح وأدوات لكتابة الوثائق.
حول REST APIs
تسهل واجهات برمجة تطبيقات REST على تطبيقات الإنترنت المختلفة التواصل مع بعضها البعض. يمكنك الحصول على بيانات من برنامج آخر عند استخدام أحد البرامج. يمكنك استخدام RESTful API بدلاً من الطرق التقليدية ، والتي تستغرق وقتًا أطول وتكون أقل أمانًا. باستخدام API ، يمكنك الحصول على البيانات من نظام دون التعامل مع واجهة المستخدم.
REST هو أسلوب تصميم وبرمجة معماري شائع لمنصات الوسائط التشعبية المتصلة بالشبكة وتقنيات الويب الأخرى. على سبيل المثال ، ستعيد واجهة برمجة تطبيقات Instagram حالة المستخدم وهويته واتصالاته وتغريداته المشتركة عندما يطلب مبرمج الحصول على كائن العميل. بفضل تكامل API ، هذا ممكن.
كيف تكتب وثائق API؟
يجب أن يكون التوثيق الأفضل بمثابة دليل وأداة تعليمية ، مما يمكّن المطورين من العثور بسرعة على التفاصيل التي يحتاجون إليها بسرعة وتعلم كيفية دمج التقنية التي يفكرون فيها من خلال مراجعة الوثائق. نتيجة لذلك ، يجب أن تكون الوثائق الكافية موجزة ومرئية ، وتقدم ما يلي:
- وصف مفصل لما تفعله التقنية أو العنصر
- عمليات الاستدعاء التي تنقل التفاصيل المهمة إلى المطورين ، مثل المشكلات والتنبيهات
- مثال على مكالمة مع محتوى نوع الوسائط المطابق
- قائمة مرجعية بالمتغيرات التي تستخدمها هذه التقنية ، مع معلومات عن أنواعها ، ومتطلبات هيكلية معينة ، وإذا كانت ضرورية.
- مثال على استجابة بجسم من نوع الوسائط
- نماذج من النصوص المكتوبة بعدة لغات تحتوي على جميع التعليمات البرمجية الضرورية (مثل Java و .Net و Ruby وما إلى ذلك)
- مثيلات SDK
- يوضحون كيفية استخدام SDK لهجتهم للوصول إلى الخدمة أو الإجراء.
- أنشطة قيّمة لاختبار وتجربة طلبات واجهة برمجة التطبيقات (وحدة تحكم واجهة برمجة التطبيقات ، دفتر ملاحظات واجهة برمجة التطبيقات)
- عادة ما يتم استجواب الاستفسارات والمواقف ذات الرموز.
- مراجع لمواقع ذات صلة (أمثلة أخرى ، مدونات ، إلخ.)
أفضل النصائح لكتابة وثائق RESTful API
خطط لاستراتيجيتك لكتابة الوثائق
عند بدء عملية التوثيق ، يجب عليك وضع استراتيجية شاملة. نتيجة لذلك ، سيرتفع احتمال نجاحك. افهم القراء الذين تنشئ الوثائق لهم قبل توثيق REST APIs. يمكنك بسهولة اختيار النظام الأساسي والأسلوب والتخطيط المناسب لوثائقك إذا كنت على دراية بجمهورك المستهدف.
سيكون من الأسهل بالنسبة لك إنتاج مواد ذات صلة من شأنها تحسين استخدام واجهة برمجة التطبيقات الخاصة بك إذا كان لديك فهم واضح لأهداف ونطاق توثيق واجهات برمجة تطبيقات REST. يمكنك تنظيم الوثائق لتلبية متطلبات المستخدم بشكل أفضل عن طريق كتابة REST APIs معهم في الاعتبار.
تذكر أن المستهلكين لديهم تمثيل عقلي لسيناريو التشغيل الخاص بك عندما يستخدمون واجهات برمجة التطبيقات الخاصة بك. على سبيل المثال ، من المحتمل أن يفكر المستخدمون في تكاليف مستندات API والمرتجعات والعملاء وبطاقات الخصم إذا كنت تقدم طريقة دفع.
لذلك ، فإن تنظيم مستنداتك بهذه الطريقة يجعلها منطقية. ضع في اعتبارك دراسة وثائق Stripe API. يقدمون مقدمة جيدة قبل التجميع المنطقي لواجهات برمجة التطبيقات. يقدم GitHub توضيحًا قويًا لوثائق RESTful API المنظمة جيدًا ، مع أقسام "معلومات GitHub والمشكلات والأعضاء."
يتيح لك GitHub إنشاء طلبات سحب وفروع والمزيد. مستندات GitHub API مفتوحة المصدر. أفضل جزء في GitHub هو أنه يسعى دائمًا لتحسين تجربة المطور بطرق مهمة.
قم بتضمين الأقسام الأساسية
يجب أن تتضمن وثائق RESTful API الممتازة قدرًا معينًا من الأجزاء. هذه الأجزاء الأساسية ضرورية لتعزيز الوضوح وزيادة قبول واجهات برمجة تطبيقات REST عند توثيقها. يجب مراعاة بعض العناصر الأساسية أثناء توثيق واجهات برمجة تطبيقات REST.
- مقدمة إلى REST API
- كيفية الحصول على بيانات اعتماد المستخدم
- الموارد اللازمة لاستخدام API
- رسائل أخطاء عند الاتصال بواجهة برمجة التطبيقات
- شروط الاستخدام
حافظ على النزاهة وابتعد عن المصطلحات
يعد الاتساق في استخدام المصطلحات عبر النص بأكمله طريقة أخرى مفيدة لوثائق RESTful API. استخدم أسلوب كتابة متسق خالٍ من التناقضات اللغوية والترميزية. قم بإزالة أي أجزاء غير واضحة أو صعبة الفهم بعد التدقيق اللغوي الشامل للمحتوى الخاص بك.
استخدم دائمًا معايير مصطلحات ومفردات متسقة. استخدم خيالك عند استخدام بروتوكولات HTTP ورموز الحالة وأسماء العناصر الشائعة الأخرى التي قد تؤدي إلى سوء الفهم. على سبيل المثال ، عند وصف واجهات برمجة تطبيقات REST ، يجب استخدام فعل GET HTTP للاستعلام عن البيانات من مورد محدد. لن تضطر إلى كتابة العديد من المبررات إذا التزمت بالمعايير المعروفة ، وستكون وثيقتك أسهل في القراءة. قد يساعدك أيضًا إذا امتنعت أيضًا عن الإفراط في استخدام اللغة التقنية في وصف واجهة برمجة التطبيقات الخاصة بك. تأكد من استخدام لغة مباشرة تتحدث عن متطلبات جمهورك الأساسي.
أضف الرسوم التوضيحية التفاعلية
يستمتع معظم المطورين باختبار ما قرأوه في الوثائق لتحديد ما إذا كانت فعالة. في لغة البرمجة التي يعرفها غالبية المطورين ، قم بتضمين برامج الأمثلة الديناميكية. هذا سيجعل تطوير API أقل تعقيدًا.
يعد تضمين أمثلة REST API الديناميكية تقنية فعالة لخفض منحنى التعلم أثناء استخدام API الخاص بك. بالإضافة إلى ذلك ، يمكنك تضمين معلومات الاختبار التي يمكن للمستخدمين استخدامها لإرسال الاقتراحات وفحص أنواع الردود التي يتلقونها.
عند توثيق واجهات برمجة تطبيقات REST ، يمكنك تضمين مواد أخرى غير الأمثلة الحية. سيساعد هذا المستخدمين في تحقيق أقصى استفادة من واجهة برمجة التطبيقات بما يتجاوز المعلومات المقدمة في التعليمات. دليل إعداد الحساب ، والأطر ، وأدوات التطوير ، والندوات هي بعض المواد التي يمكن استخدامها لزيادة وصف واجهة برمجة التطبيقات.
اكتب لمنصب مستوى الدخول
غالبًا ما يقوم الكتاب المحترفون ، وليس المطورون ، بإنشاء الوثائق. وذلك لأن الكتاب التقنيين متخصصون في تفسير المفاهيم التقنية إلى لغة مفهومة. ومع ذلك ، يستخدم العديد من الكتاب التقنيين المفردات التقنية في كتيباتهم. تم تطوير كل واجهة برمجة تطبيقات مع وضع جمهور محدد في الاعتبار.
تتمتع مستندات API بنسبة مشاهدة واسعة ، بما في ذلك المطورين وفرق الحكم والمراقبين. يتعامل المطورون مع الوثائق. يفهم فريق الحكم ، مثل المهندسين وكبار المسؤولين التنفيذيين ، بسرعة ما إذا كانت واجهة برمجة التطبيقات مطابقة مناسبة ، والمشاهدين ، مثل الكتاب التقنيين والمراسلين ومنافسيك.
هؤلاء الأفراد لديهم واجبات ومواهب مميزة ويجب الاسترخاء أثناء عرض وثائق REST API الخاصة بك. نتيجة لذلك ، يجب أن تركز على المستهلكين الأقل خبرة. قم بتطبيق التقنيات المذكورة أعلاه عند توثيق واجهات برمجة تطبيقات REST لضمان أن الأعمال الورقية لـ REST API مفهومة من قبل الأشخاص بدرجات متفاوتة من معرفة API.
أفضل أداة لإنشاء وثائق RESTful API
الطريقة التي تم من خلالها تبسيط الوثائق الفنية باستخدام أدوات Restful APIs. يمكن للكتاب التقنيين استخدام أدوات توثيق REST API هذه لإنشاء منشورات فنية إذا كانوا على دراية بالشفرات. نظرًا لانتشار استخدام منشئي وثائق API على نطاق واسع ، فإن أشهر المنتجين يتمتعون بالمجان ويدعم OpenAPI v3 أدناه. يستخدم الكتاب الفنيون هذه الموارد لإنتاج وثائق REST API.
SwaggerHub
SwaggerHub عبارة عن منصة توثيق رقمية لواجهة برمجة التطبيقات تم إنشاؤها لتبسيط وتسريع وثائق Rest API ، مما يجعلها مثالية للفرق والشركات. يمكنك الالتزام بسرعة أكبر بمواصفات OpenAPI ( OAS) ، التي كان يُشار إليها سابقًا باسم Swagger ، باستخدام محرر واجهة برمجة التطبيقات.
بعض ميزاته هي:
- الإبلاغ الفعال عن الخطأ والإكمال التلقائي للغة
- إرشادات تصميم واجهة برمجة التطبيقات المتكاملة التي تطبق المعايير باستمرار
- مواقع الويب لتخزين واستخدام بناء جملة OAS الشامل عبر واجهات برمجة التطبيقات
- تتبع المشاكل في الوقت الحقيقي والتعليقات
- يقدم تجربة مطور ممتازة
Redocly
تتم أتمتة عملية توثيق REST API باستخدام حلول مهام سير العمل من Redocly. يمكنك التعامل مع الوثائق الخاصة بك مثل رمز البرنامج باستخدام المستندات الافتراضية عن طريق حفظها في برنامج إصدار خاص ، وإنشاء إجراء تدقيق ، وتسليمه إلى إعدادات مختلفة. تسمح لك Redocly المستخدم "إعادة تحديد" ومحاولة التحقق وآليات المصادقة الأخرى بضمان عمل فريقك بشكل فعال وآمن معًا. تعد إمكانية عرض Redocly ميزة فريدة أخرى. لضمان تقييم تعديلاتك ومناقشتها قبل إرسالها إلى الجمهور ، يمكنك معاينة كل مشروع وطلبات التصحيح.
Stoplight
باستخدام الأداة المساعدة للكتابة REST API الخاصة Stoplight ، يمكنك إنشاء مستندات API وتقديمها رقميًا. باستخدام هذا البرنامج ، يمكنك إنشاء وثائق REST API ديناميكية يمكنك توزيعها داخليًا وخارجيًا لعامة الناس. يمكنك دمج المقالات الإرشادية وكتيبات التعليمات ونماذج التعليمات البرمجية التي تم إنشاؤها في مجموعة متنوعة من لغات البرمجة ، مثل JavaScript و Python و Java.
يمكنك نشر وثائقك على Stoplight ، وهي إحدى الميزات المهمة لحل التوثيق REST API الخاص بنا. هذا يحررك من القلق بشأن تشغيل الخوادم ويجعل من السهل استخدام الموصلات للتعامل مع الأذونات وتتبع المقاييس.
ReadMe
يمكن أن تصبح مستندات API الخاصة بك مركزًا ديناميكيًا لمطوريك باستخدام ReadMe. يمكنهم إنشاء أمثلة التعليمات البرمجية تلقائيًا ، وتغيير المواد في محرر ReadMe ، ودمج تعديل موصى به ، والرد على الاستفسارات في لوحة المناقشة ، والمزيد في هذا المركز.
تتمثل إحدى أهم مزايا ReadMe في أنه يحلل التحليلات مثل زيارات الصفحة ، وطلبات API ، وإخفاقات API ، والاستعلامات إلى مواقع الويب المختلفة ، من بين أمور أخرى ، حتى تتمكن من معرفة كيفية استخدام واجهة برمجة التطبيق ووثائق REST API بمرور الوقت. باستخدام هذه المقاييس ، قد يحدد طاقمك مكان تركيز جهودهم لتحسينه.
apiDoc
يُنشئ حل توثيق REST API مفتوح المصدر يسمى apiDoc وثائق من قاعدة كود تحتوي على تفاصيل API. مع كل لغة برمجة تقريبًا ، فهي متوافقة. يمكن للمهندسين ملاحظة ما تم تعديله بين إصدارات API لأن apiDoc يتيح لك القيام بذلك. هذا يسهل التعامل مع تحديثات API بشكل نظيف ، والمعروف غالبًا باسم إصدار API.
DapperDox
تم تطوير DapperDox بواسطة مؤلفي وثائق RESTful API لكتاب وثائق REST API من أجل منح الكتاب الحرية التي يريدونها والمطورين سهولة القراءة التي يحتاجونها. يعد حل مستندات واجهة برمجة تطبيقات الويب هذا مثاليًا لإنشاء مجموعة متماسكة من الوثائق التي تحتوي على تعليمات واضحة ومعايير واجهة برمجة تطبيقات الويب لأنه يتيح للكتاب إضافة مواد ذات صلة إلى موقع وصف تم إنتاجه. بالإضافة إلى ذلك ، يمكنك الإسناد الترافقي حسب الضرورة ، ووصف متطلبات API المختلفة كمجموعة من السلع ، وتحديد السمات لتنسيق أوراقك بشكل مختلف.
DocGen بواسطة LucyBot
يمكنك إنشاء وإدارة وثائق API الديناميكية باستخدام LucyBot DocGen. يقوم هذا البرنامج بإنشاء وثائق لكل طريقة API وحجة وردود على الفور. يمكنك إنشاء وحدة تحكم واجهة برمجة التطبيقات (API) لتمكين المنشئين والمستخدمين من تنفيذ طلبات واجهة برمجة التطبيقات التجريبية لفحص واجهة برمجة التطبيقات (API) الخاصة بك واستكشاف الأخطاء وإصلاحها وفهمها على الأرجح. يمكنك أيضًا إنشاء عمليات تُظهر للمستخدمين بالضبط الترميز الذي يجب عليهم إنشاؤه والمراحل التي يجب عليهم اتباعها لإكمال مهمة معينة في لغة البرنامج التي يختارونها.
AppMaster
على عكس الأنظمة الأساسية الأخرى ، يلغي AppMaster الحاجة إلى مطور لإنشاء وثائق REST API يدويًا وتحديثها. يقوم النظام الأساسي تلقائيًا بإنشاء وتحديث وثائق REST API بتنسيق Swagger ( OpenAPI) لكل تطبيق ويتضمن أيضًا Swagger UI في كل تطبيق خادم لتسهيل تكامل مطوري الطرف الثالث مع التطبيقات التي تم إنشاؤها. بالإضافة إلى ذلك ، تتضمن منصة AppMaster ، عند إنشاء وثائق REST API ، أوصافًا لنقاط النهاية والعمليات التجارية ذات الصلة تلقائيًا في وصف كل نقطة نهاية ، مما يلغي تمامًا حاجة المطور لإنشاء الوثائق أو تحديثها.
الكلمات الأخيرة
جميع أدوات مستند API التي تم تناولها في هذه المقالة قادرة على إنتاج وثائق API عالية الجودة. من المستحيل إعلان أن أي أداة واحدة هي الأعظم. يتم تحديد الخبرة والمعايير الكاملة لبرنامج توثيق API من خلال معايير العميل ومفاهيمه وأهدافه ومتطلبات التوثيق.
