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

أنت تعرض مستندات Apigee Edge.
انتقل إلى مستندات Apigee X. معلومات

تتيح لك أداة Smart Docs توثيق واجهات برمجة التطبيقات على بوابة مطوّري البرامج في Drupal 7 بطريقة تجعل مستندات واجهة برمجة التطبيقات تفاعلية بالكامل. التوثيق التفاعلي يعني أن مستخدمي البوابة يمكنهم:

  • الاطّلاع على مزيد من المعلومات عن واجهات برمجة التطبيقات
  • إرسال طلب مباشر إلى واجهة برمجة التطبيقات
  • الاطّلاع على ردّ مباشر تم عرضه من واجهة برمجة التطبيقات

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

واجهة برمجة التطبيقات Edge management API هي واجهة برمجة تطبيقات RESTful تتيح لك الوصول إلى خدمات واجهة برمجة التطبيقات باستخدام أي عميل HTTP. يستخدم Apigee ميزة Smart Docs لإنشاء مستندات تفاعلية لإدارة Edge. واجهة برمجة التطبيقات. يمكنك الاطّلاع على وثائق واجهة برمجة التطبيقات هنا.

مثال على بوابة Smart Docs

لاستخدام Smart Docs، يجب أن يكون لديك بوابة لخدمات مطوّري البرامج في Apigee. لمزيد من المعلومات، يُرجى مراجعة إنشاء مطور البوابة.

من الصفحة الرئيسية لبوابة المطوّرين، انقر على واجهات برمجة التطبيقات في شريط التنقل العلوي من أجل عرض صفحة وثائق واجهة برمجة التطبيقات.

هناك واجهتا برمجة تطبيقات موثقتان على البوابة: Hello World وPet Store Example.

تم إنشاء واجهة برمجة تطبيقات Hello World من واجهة OpenAPI المستهدفة الوهمية المواصفات: mocktarget.yaml لمزيد من المعلومات، يُرجى الاطّلاع على https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.

تم إنشاء Pet Store Example API من الإصدار التجريبي لمتجر الحيوانات الأليفة الكلاسيكي.

استكشاف واجهة برمجة تطبيقات Hello World:

  1. انقر على Hello World API. يتم عرض صفحة ملخص واجهة برمجة التطبيقات Hello World:
  2. انقر على عرض تأكيد واجهة برمجة التطبيقات. يعد تطبيق Smartالمستندات لهذا المورد المعروضة:
  3. انقر على إرسال هذا الطلب.
  4. الاطّلاع على الردّ الذي تم عرضه: 
    HTTP/1.1 200 OK
Connection:
keep-alive
Content-Length:
18
Content-Type:
text/html; charset=utf-8
Date:
Tue, 21 Jun 2016 21:49:32 GMT
ETag:
W/"12-Jb9QP1bUxNSmZkxQGt5KLQ"
X-Powered-By:
Apigee
<H2>I <3 APIs</H2>
  5. انقر على علامة التبويب طلب للاطّلاع على الطلب أو على cURL. للاطّلاع على طلب cURL المقابل.

كيفية توثيق واجهات برمجة التطبيقات باستخدام Smart Docs

وتمثل Smart Docs واجهات برمجة التطبيقات باستخدام نموذج، حيث يحتوي النموذج على جميع معلومات عن واجهات برمجة التطبيقات. تستخرج البوابة معلومات حول واجهات برمجة التطبيقات من النموذج إلى عرض صفحات المستندات على البوابة كعُقد Drupal، حيث تتوافق كل عُقدة في Drupal إلى صفحة من المستندات على البوابة

في ما يلي الخطوات العامة التي يجب اتّباعها لاستخدام تطبيق Smartالمستندات:

  1. عليك ضبط وحدة Drupal Smart Docs على البوابة.
  2. إنشاء نموذج Smart Docs.
  3. إضافة واجهات برمجة تطبيقات إلى النموذج من ملف WADL، وهو OpenAPI (المعروف سابقًا باسم Swagger) أو مواصفاته أو يدويًا.
  4. اعرض النموذج كمجموعة من عُقد Drupal. كل عقدة Drupal يحتوي على معلومات حول واجهة برمجة تطبيقات واحدة. على سبيل المثال، إذا كان أحد الموارد في واجهة برمجة التطبيقات يتيح كلاً من POST وطلب PUT، ينشئ Smartdocs عقدة Drupal منفصلة لكل من POST وPUT.
  5. انشر عُقد Drupal. بعد النشر، يمكن لمستخدمي البوابة عرض للتفاعل مع واجهة برمجة التطبيقات.
  6. عدِّل عُقد Drupal، إما قبل نشرها أو بعدها. يمكنك تعديل عُقد Drupal باستخدام مُحرِّر Drupal أو من خلال تعديل ملف WADL الأصلي أو مواصفات OpenAPI. عند الانتهاء من تعديل ملف WADL أو مواصفات OpenAPI، قم باستيراد إلى النموذج كنسخة جديدة، ثم عرض التغييرات ونشرها.
  7. تفعيل بروتوكول أمان طبقة النقل (TLS) ونظرًا لأن تطبيق Smartالمستندات يمكنه إرسال بيانات اعتماد المصادقة إلى كجزء من عملية تقديم طلب إلى واجهات برمجة التطبيقات، يجب تفعيل بروتوكول أمان طبقة النقل (TLS) على البوابة والتأكد من أن بيانات الاعتماد هذه آمنة. في بيئات الإنتاج والاختبار البوابة، توفّر Apigee شهادة بروتوكول أمان طبقة النقل (TLS) المطلوبة لإجراء طلبات https:// . ومع ذلك، قبل أن تذهب مباشرة مع البوابة، يجب الحصول على شهادة بروتوكول أمان طبقة النقل (TLS) الخاصة بك وتفعيل بروتوكول أمان طبقة النقل. لمزيد من المعلومات، راجع استخدام بروتوكول أمان طبقة النقل (TLS) في البوابة.

لمحة عن نماذج SmartDoc ونماذجها

عند إنشاء نموذج في البوابة، يتم تخزين النموذج في متصفّح Edge. مؤسستك، وليس في Drupal. النموذج عبارة عن كتلة كبيرة من JSON لها اسم داخلي (مثل "my-smartdocs-api")، وهي تحدد بنية واجهة برمجة التطبيقات. من ناحية أخرى، يعرض النموذج بتنسيق HTML ويوفر واجهة تحرير للنموذج. أي تعديلات على واجهة برمجة التطبيقات الموجودة في البوابة تلقائيًا إلى النموذج المصدر.

تم التخزين في المؤسسة

مُخزَّن في Drupal

الطرازات

نماذج

عُقد Drupal مع وظيفة تعديل

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

تتحكم النماذج في شكل ومظهر تطبيق Smart Docs وهذه النماذج (الإدارة بواسطة المقاود وملفات CSS) التي يتم تخزينها مع كل مثيل بوابة. لذلك يمكن نظريًا لكل بوابة استخدام قالب فريد لكل نموذج. مع ذلك، من بين وسائل الراحة التي يوفّرها إطار العرض هو أن النموذج التلقائي (إما نموذج Apigee التلقائي أو نموذج تقدّمه) يتم تلقائيًا تطبيقها على كل نموذج.

يوضح الرسم التخطيطي التالي العلاقة بين النماذج والبوابات. تظهر الأسهم الخضراء مزامنة تلقائية.

ويسرد أمر cURL التالي جميع النماذج في مؤسستك:

curl -v https://api.enterprise.apigee.com/v1/o/{your_org}/apimodels/ -u edge_org_admin@example.com

تهيئة وحدة Smart Docs

استخدمت Apigee تقنية Smart Docs كوحدة Drupal مخصَّصة. اتّبِع الإجراء التالي تهيئة وحدة Smart Docs.

لضبط وحدة Smart Docs، اتّبِع الخطوات التالية:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. اختَر الوحدات في قائمة إدارة Drupal. قائمة بكل ستظهر وحدات Drupal المثبَّتة.
  3. فعِّل وحدة SmartDocs.
  4. احفظ الإعداد.
  5. اختَر الوحدات في قائمة مشرف Drupal.
  6. حدد Smart Docs -> الأذونات والتأكد من "تنفيذ الإدارة" المهام الخاصة بوحدة Smart Docs" لـ "المشرف" تمكين الدور.
  7. حدد الإعداد > بوابة مطوّري البرامج في إدارة Drupal القائمة.
  8. اضبط مهلة الاتصال ومهلة الطلب على 16. ثوانٍ.
  9. احفظ الإعداد.
  10. ضبط إعدادات عنوان URL:
    1. حدد الإعداد > البحث والبيانات الوصفية > الأسماء المستعارة لعناوين URL > الإعدادات من قائمة Drupal.
    2. اضبط الحد الأقصى لطول الاسم المستعار والحدّ الأقصى للمكوِّن. الطول إلى 255
    3. وسِّع علامات الترقيم.
    4. بالنسبة إلى القوس المعقوف الأيسر ({) والقوس المعقوف أيمن (})، اختر عدم اتخاذ أي إجراء (عدم الاستبدال).
    5. انقر على حفظ الإعداد.
  11. إذا كانت بوابة المطوِّر ستظهر للمستخدمين في شبكة داخلية بدون الوصول إلى الإنترنت أو إذا كانت مجموعة فرعية من واجهات برمجة التطبيقات على شبكة خاصة، قم بتهيئة واجهة برمجة التطبيقات Smart Docs على النحو التالي:
    1. حدد الإعداد > Smartdocs في إدارة Drupal القائمة.
    2. عليك توسيع قسم الإعدادات المتقدمة.
    3. عدِّل حقل عنوان URL لخادم وكيل Smartالمستندات على النحو التالي: <host>/smartdocs/v1/sendrequest
      يجب أن توفر المساعدة المضمّنة القيمة المطلوبة لبيئتك. مثال:
      https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest

      الإعداد الافتراضي لهذا الحقل هو https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest
    4. انقر على حفظ الإعداد.

إنشاء نموذج

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

ويحدد كل نموذج اسمًا داخليًا فريدًا يحدد أيضًا عنوان URL الأساسي تم إنشاء عُقد Drupal. يظهر عنوان URL لكل عقدة Drupal على النحو التالي:

http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>

حيث:

  • drupalBasePath: عنوان URL الأساسي للبوابة.
  • internalName: الاسم الداخلي للنموذج.
  • httpMethod: طريقة HTTP لواجهة برمجة التطبيقات، مثل: get أوput أو post أو حذف.
  • resourcePath: مسار المورد.

على سبيل المثال، إذا حددت الاسم الداخلي على أنه "mymodel"، فإن عنوان URL للعنصر الذي تم إنشاؤه عقدة Drupal لطلب GET إلى مورد باسم " /books" :

http://prod-myco.devportal.apigee.com/mymodel/apis/get/books

لإنشاء نموذج

عند إنشاء نموذج، يتم تخزينه في مؤسسة Edge كمصدر لواجهة برمجة التطبيقات. البنية. لمزيد من المعلومات، يمكنك الاطّلاع على لمحة عن نماذج SmartDoc النماذج.

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. انقر على المحتوى >. Smartالمستندات في إدارة Drupal القائمة.
  3. اختَر نموذج جديد في أعلى الصفحة.
  4. أدخِل الحقول التالية:
    • الاسم: هو اسم النموذج الذي سيتم عرضه على الموقع الإلكتروني.
    • الاسم الداخلي: أثناء كتابة الاسم، يظهر اسم عرض الأسماء. الاسم الداخلي للنموذج الذي يجب أن يكون فريدًا بين جميع النماذج. يجب ألا يحتوي الاسم الداخلي إلا على أحرف صغيرة وأرقام وواصلات بدون مسافات. انقر على تعديل لتعديل هذا الاسم.
    • الوصف: هو وصف للنموذج.
  5. اختَر إنشاء نموذج.

بعد إنشاء النموذج، ستتم إعادة توجيهك إلى صفحة النموذج. من هناك، يمكنك استخدام القائمة المنسدلة للعمليات bx بهدف:

  • استيراد ملف WADL يصف واجهة برمجة التطبيقات أو تحديد عنوان URL لواجهة OpenAPI المواصفات التي تصف واجهة برمجة التطبيقات.
  • إضافة النسخة السابقة إلى النموذج
  • عدِّل إعدادات النموذج، بما في ذلك أوراق الأنماط التي يستخدمها الأمثل.
  • صدِّر النموذج إلى ملف.
  • احذف النموذج.

إضافة واجهات برمجة التطبيقات إلى نموذج

يمكنك إضافة واجهات برمجة التطبيقات إلى نموذج عن طريق:

  • استيراد ملف WADL يحتوي على تعريف واجهة برمجة التطبيقات
  • استيراد مواصفات OpenAPI (الإصدار 2.0 أو 1.2 من OpenAPI)
  • إنشاء الموارد والطرق يدويًا

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

فيديو: يمكنك مشاهدة فيديو قصير للتعرّف على كيفية إضافة واجهات برمجة التطبيقات إلى نموذج Smart Docs من خلال استيراد مواصفات OpenAPI.

استيراد WADL

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

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. اختَر المحتوى > Smart Docs في Drupal إدارة الموقع.
  3. اختَر النموذج الذي تريد تعديله.
  4. ضمن العمليات، اختَر استيراد.
  5. اختَر WADL في القائمة المنسدلة Choose Format (اختيار التنسيق) في صفحة استيراد Smart Docs.
  6. اختَر ملف أو عنوان URL في تحميل. القائمة المنسدلة "النوع".
    1. إذا اخترت ملف، انتقِل إلى ملف WADL.
    2. إذا اخترت عنوان URL، حدِّد عنوان URL لملف WADL.
  7. انقر على استيراد لاستيراده إلى النموذج. يمكنك الآن لعرض النموذج.
  8. ستتم إعادة توجيهك إلى صفحة معلومات النموذج حيث يمكنك الآن عرض الأمثل.

استيراد OpenAPI المواصفات

بعد إنشاء نموذج بنجاح، يمكنك استيراد واجهة OpenAPI (المعروفة سابقًا باسم Swagger) المواصفات يدعم Edge الإصدارين 1.2 و2.0 من OpenAPI.

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

لاستيراد مواصفات OpenAPI:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. اختيار المحتوى > Smart Docs في قائمة إدارة Drupal
  3. اختَر النموذج الذي تريد تعديله.
  4. ضمن العمليات، اختَر استيراد.
  5. اختَر Swagger JSON أو Swagger YAML في علامة التبويب اختيار التنسيق من القائمة المنسدلة في صفحة استيراد Smart Docs.
  6. اختَر ملف أو عنوان URL في القائمة المنسدلة نوع التحميل (يجب اختيار عنوان URL للإصدار 1.2 من OpenAPI).
    1. إذا حددت ملفًا، تصفّح للوصول إلى واجهة برمجة تطبيقات OpenAPI. المواصفات
    2. إذا اخترت عنوان URL، حدِّد عنوان URL لواجهة OpenAPI. المواصفات
  7. انقر على استيراد لاستيراده إلى النموذج.
  8. ستتم إعادة توجيهك إلى صفحة معلومات النموذج حيث يمكنك الآن عرض الأمثل.

إنشاء الموارد يدويًا والطرق المتاحة

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

لإضافة واجهة برمجة تطبيقات يدويًا:

  1. قم بإنشاء نسخة جديدة من النموذج.

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

    https://myCompany.com/v1

    وعند إضافة موارد إلى النموذج، تعمل على توسيع المسار الأساسي.
  2. حدد موردًا واحدًا أو أكثر للنموذج. يندمج مسار المورد مع المسار الأساسي مراجعة النموذج لتحديد عنوان URL الكامل للمورد. على سبيل المثال، إذا كان المورد مسارًا لـ " /login"، فإن عنوان URL الكامل للمورد هو:

    https://myCompany.com/v1/login
  3. حدد طريقة واحدة أو أكثر لكل مورد. تحدد الطريقة فعل HTTP الذي يمكن على مورد. على سبيل المثال، بالنسبة إلى الملف " /login" المصدر، فأنت تدعم طريقة POST لتسجيل الدخول DELETE لتسجيل الخروج. هذا المورد لا يدعم أفعال HTTP الأخرى، مثل PUT أو GET. لذلك، حدد طريقتين للمورد، إحداهما لطريقة POST والأخرى لكلمة DELETE.

    تستخدم هذه الطريقة عنوان URL للمورد من المورد الرئيسي. لذلك، جميع الطرق التي لها نفس يتم تحديد عنوان URL ضمن مورد واحد في Smart Docs.

كقاعدة عامة:

  • أنشئ نموذج Smart Docs مختلفًا لكل مسار أساسي فريد في واجهة برمجة التطبيقات.
  • حدد مورد Smart Docs مختلف لكل مورد فريد في واجهة برمجة التطبيقات الخاصة بك.
  • حدِّد طريقة Smart Docs مختلفة لكل فعل HTTP متوافق مع أحد الموارد.

إنشاء نسخة جديدة من أحد النماذج

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

لإنشاء نسخة جديدة من أحد النماذج:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. اختيار المحتوى > Smart Docs في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد تعديله، اختَر إضافة نسخة سابقة. ضمن العمليات.
  4. في صفحة إضافة مراجعة واجهة برمجة التطبيقات، أدخِل المعلومات التالية:
    • الاسم المعروض: اسم النسخة السابقة كما يظهر في البوابة.
    • رقم تعريف الإصدار: معرّف قصير للنسخة السابقة
    • الوصف: هو وصف للنسخة السابقة.
    • عنوان URL الأساسي: هو عنوان URL الأساسي لجميع واجهات برمجة التطبيقات في مراجعة النموذج. حاسمة استخدام عناوين URL أساسية مختلفة لكل مراجعة. على سبيل المثال، تقوم بتضمين إصدار في عنوان URL الأساسي. بالنسبة إلى المراجعة الأولى للنموذج، يكون عنوان URL الأساسي هو:
      https://myCompany.com/v1
      بالنسبة إلى المراجعة التالية، يمكن أن يكون عنوان URL الأساسي كالآتي:
      https://myCompany.com/v2
  5. حدِّد إضافة نسخة سابقة. ستتم إعادة توجيهك إلى صفحة مراجعة النموذج. يمكنك الآن تحديد الموارد في النموذج.

تحديد المورد

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

لتحديد مورد:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. اختيار المحتوى > Smart Docs في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد تعديله، ضمن العمليات، اختَر واجهة برمجة التطبيقات (API). النُسخ السابقة لعرض جميع النُسخ السابقة من أحد النماذج.
  4. اختَر نسخة سابقة لتعديلها.
  5. في صفحة النسخة السابقة، حدد إضافة مورد من القائمة المنسدلة.
  6. في صفحة إضافة مورد، أدخِل المعلومات التالية:
    • الاسم المعروض: اسم المورد.
    • المسار: مسار المورد، والذي يبدأ بـ "/". قيمة تم دمج المسار مع عنوان URL الأساسي لمراجعة النموذج لإنشاء عنوان URL الكامل للمورد.
    • الوصف: وصف المورد.
    • المَعلمات: يمكنك اختياريًا إدخال كائن JSON الذي يحدّد كل مَعلمة. في المورد. يتم توضيح هذه المعلمات في ما يلي.
  7. اختَر إضافة مورد. ستتم إعادة توجيهك إلى صفحة النموذج. يمكنك الآن تحدد الطرق الموجودة في المورد.

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

وبدلاً من ذلك، يمكنك تحديد المعلَمات باستخدام إحدى الطرق. على سبيل المثال، قد تتوافق طريقة POST معلمات طلب البحث غير المتوافقة مع طريقة DELETE. لذلك، أضف أي معلمات الخاصة بطريقة معينة عند تحديد الطريقة، كما هو موضح أدناه.

تعرض الصورة التالية صفحة Smart Docs الحالية الخاصة بالـ موافقة Apigee على تطبيق المطوِّر أو إبطاله مع تمييز كل نوع من أنواع المَعلمات:

يتم تحديد كل نوع مَعلمة من خلال كائن JSON:

النوع

كائن JSON

ملاحظات

النموذج

{
"dataType": "string",
"defaultValue": "",
"description": "اسم المؤسسة."،
"name": "org_name",
"مطلوب": true,
"النوع": "TEMPLATE"
}

مَعلمات النموذج مطلوبة دائمًا، لذا اضبط required على true واحذف القيمة على defaultValue.

قيمة description في نافذة منبثقة عندما يمرر المستخدم مؤشر الماوس فوق عنوان URL في صفحة Smart Docs.

طلب البحث

{
"dataType": "string",
"defaultValue": "",
"description": "الموقع الجغرافي.",
"name": "w",
"مطلوب": true,
"النوع": "QUERY"
}

لا يزال بإمكان مَعلمات طلب البحث المطلوبة تحديد defaultValue، ولكنها لا تفعل ذلك في كثير من الأحيان.

بالنسبة إلى مَعلمات طلب البحث الاختيارية، اضبط required على false وحدِّد قيمة على defaultValue.

العنوان

{
"dataType": "string",
"defaultValue": "application/json",
"description": "تحديد بتنسيق <code>application/json</code>.",
"name": "نوع المحتوى",
"مطلوب": true,
"النوع": "رأس"
}

لاحظ كيف يمكنك استخدام علامات HTML في الوصف.

تحدِّد معلَمة النموذج متغيّرًا في مسار المورد. على سبيل المثال، تقوم بتعريف اثنين معلَمات النموذج على المورد. لاحظ كيف أن كل تعريف لكل معلمة في صفيف المعلمة مفصولة بفاصلة:

[
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the organization name.",
  "name": "org_name",
  "required": true,
  "type": "TEMPLATE"
 },
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the user email.",
  "name": "developer_email",
  "required": true,
  "type": "TEMPLATE"
 }
]

ويمكنك بعد ذلك استخدام مَعلمات النموذج في تعريف مسار المورد، المُضمَّن في "{}". على سبيل المثال، يمكنك ضبط المسار على:

/login/{org_name}/{developer_email}

في صفحة واجهة برمجة التطبيقات لتطبيق Smart Docs، على المستخدم تعديل عنوان URL لتحديد الجزء org_name وdeveloper_email من عنوان URL قبل. فيمكنه إرسال طلب.

تحديد طريقة

حدد طريقة واحدة أو أكثر لكل مورد. يحدد تعريف الطريقة فعل HTTP التي يمكن استدعاؤها في المورد. يمكن أن يكون للمورد طريقة واحدة محددة عليه، أو طرقًا متعددة.

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

تعرِض الصورة التالية صفحة Smartالمستندات الحالية لواجهة برمجة التطبيقات Create Developer API في Apigee مع كل منطقة من الصفحة مميزة بالقيمة المقابلة التي قمت بتعيينها عند تحديد :

تعرض الصورة التالية الصفحة نفسها ولكن مع اختيار وصف نص الطلب:

لتحديد طريقة:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. اختيار المحتوى > Smart Docs في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد تعديله، ضمن العمليات، اختَر واجهة برمجة التطبيقات (API). النُسخ السابقة لعرض جميع النُسخ السابقة من أحد النماذج.
  4. اختَر نسخة سابقة لتعديلها.
  5. في صفحة المراجعة، اختَر إضافة طريقة من القائمة المنسدلة لأحد الموارد.
  6. في صفحة تعديل الطريقة، أدخِل المعلومات التالية:
    • الاسم المعروض: اسم واجهة برمجة التطبيقات، والذي يصبح أيضًا عنوانًا لواجهة برمجة التطبيقات صفحة Drupal لواجهة برمجة التطبيقات.
    • الوصف: قدِّم وصفًا لواجهة برمجة التطبيقات.
    • الطريقة فعل: نوع فعل HTTP.
    • مخططات الأمان: حدِّد وضع المصادقة، إن وجد، . ولمزيد من المعلومات، يُرجى الاطّلاع على ضبط مصادقة Smart Docs. النوع.
    • نوع المحتوى: نوع محتوى الطلب والردّ. يمكنك الاطّلاع على أدناه حول ضبط طرق المصادقة المختلفة.
    • المَعلمات: (اختيارية) أي مَعلمات طلب بحث أو عناوين للطريقة. راجع الوصف أعلاه لإضافة معلمة إلى مورد للحصول على مزيد من المعلومات.
    • مستندات نص الطلب: (اختياري) يُرجى وصف نص الطلب. نشر مشاركة وتأخذ الطريقتان PUT نص الطلب. يمكنك استخدام هذا الجزء لوصفه. إذا لم تستخدم هذا العنصر قيمة، يتم حذف رابط الوصف ضمن نص الطلب من صفحة Smart Docs التي تم إنشاؤها.
    • مثال على نص الطلب: (اختياري) اعرض مثالاً لنص الطلب، عادة باعتباره كائن JSON أو XML. بالنسبة إلى أفعال POST وPUT، يمكن استخدام نص الطلب يتم تمرير مثال كجزء من كل طلب. يقوم مستخدمو صفحة Smart Docs بتعديل هذا قبل إرسال طلب إلى واجهة برمجة التطبيقات. إذا لم تستخدم هذه القيمة، فسيتم يتم حذف رابط القيمة ضمن نص الطلب من إنشاء صفحة Smart Docs.
    • العلامات: مصفوفة من العلامات المرتبطة بواجهة برمجة التطبيقات. يستخدم Smart Docs العلامات من أجل وتجميع واجهات برمجة التطبيقات المتشابهة معًا. على سبيل المثال، يمكنك تطبيق العلامة "إحصاءات" لجميع واجهات برمجة التطبيقات عن الإحصاء. يمكنك تجميع واجهات برمجة التطبيقات من مصادر مختلفة ضمن علامة واحدة. إذا جميعها تستخدم نفس العلامة.
  7. اختَر إضافة طريقة. ستتم إعادة توجيهك إلى صفحة النموذج. يمكنك الآن لعرض طريقتك ونشرها.

عرض نموذج

بعد إضافة واجهات برمجة التطبيقات إلى النموذج، يمكنك عرض النموذج. يحوّل العرض بيانات النموذج وصف لواجهة برمجة التطبيقات في عُقد Drupal. عند اكتمال العرض، سيكون لديك حساب واحد على Drupal. لكل واجهة برمجة تطبيقات، حيث تتطابق كل عقدة Drupal مع صفحة HTML.

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

لعرض نموذج:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. اختيار المحتوى > Smart Docs في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد عرضه، اختَر مراجعات واجهة برمجة التطبيقات ضِمن العمليات.
  4. اختَر النسخة السابقة التي تريد عرضها. يمكنك فقط عرض العُقد من مراجعة واحدة النموذج.
  5. اختَر طرق العرض.
  6. اختَر عُقد العرض من التحديث. options.
  7. انقر على تعديل.
  8. ستظهر شاشة تحميل لمعرفة مدى تقدّم العُقد التي يتم عرضها.
    بعد عرض العُقد، يظهر رقم تعريف عقدة Drupal لكل واجهة برمجة تطبيقات ضمن عمود ارتباط العقدة في النموذج. انقر على الرابط في العقدة. الارتباط للاطّلاع على العُقدة المعروضة.

بدلاً من تحديد عُقد العرض، يمكنك تحديد العرض ونشر العُقد لعرض واجهات برمجة التطبيقات ونشرها فورًا كعقدة Drupal.

عُقد النشر

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

لنشر عقدة:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. اختيار المحتوى > Smart Docs في قائمة إدارة Drupal.
  3. للنموذج الذي تريد نشره، حدد مراجعات واجهة برمجة التطبيقات ضمن العمليات.
  4. اختَر النسخة السابقة التي تريد نشرها. يمكنك نشر العُقد من نسخة مراجعة واحدة فقط. من النموذج.
  5. اختَر طرق النشر.
  6. اختَر العُقد في النسخة السابقة لنشرها.
  7. اختَر عُقد النشر من القائمة تحديث. options.
  8. انقر على تعديل.
  9. انتقِل إلى العُقدة من خلال اختيار رقم تعريف العُقدة ضمن ربط العُقدة. .

بشكل تلقائي، يكون عنوان URL لـ Drupal إلى عقدة واجهة برمجة التطبيقات المنشورة على النحو التالي: http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>. اتّبِع الإجراء التالي للتحكّم في شكل عنوان URL:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. حدد الإعداد > البحث والبيانات الوصفية > الأسماء المستعارة لعناوين URL > الأنماط في قائمة إدارة Drupal.
  3. ضمن النمط لجميع مسارات طرق Smartالمستندات، حدِّد الطريقة التي تريد استخدامها لإنشاء المسار.
  4. اختَر حفظ الإعداد.

بسبب التخزين المؤقت على البوابة، قد لا تظهر صفحات النموذج على الفور. بعد نشرها. إذا لزم الأمر، يمكنك محو ذاكرة التخزين المؤقت لـ Smartالمستندات في HTML يدويًا باستخدام الإجراء التالي:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. حدد الإعداد > Smartالمستندات في إدارة Drupal القائمة.
  3. انقر على إعادة إنشاء ذاكرات التخزين المؤقت لنماذج Smart Docs.

إلغاء نشر عقدة

يمكنك إلغاء نشر عقدة منشورة في أي وقت. يؤدي إلغاء نشر عقدة إلى جعلها غير مرئية لـ مستخدمي البوابة.

لإلغاء نشر عقدة:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. اختيار المحتوى > Smart Docs في قائمة إدارة Drupal.
  3. للنموذج الذي تريد إلغاء نشره، اختَر مراجعات واجهة برمجة التطبيقات ضمن العمليات.
  4. اختَر مراجعة النموذج للعقدة التي تريد إلغاء نشرها.
  5. اختَر العُقد في النسخة السابقة لإلغاء نشرها.
  6. اختَر عُقد إلغاء النشر من صفحة التحديث. options.
  7. انقر على تعديل.

عرض مراجعة نموذج

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

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

للاطّلاع على نسخة سابقة من أحد النماذج:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. اختيار المحتوى > Smart Docs في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد تحديثه، حدد مراجعات واجهة برمجة التطبيقات ضمن العمليات.
  4. حدد مراجعة النموذج التي تريد عرضها.
  5. اعرض العُقد وانشرها كما هو موضّح أعلاه.

تعديل عقدة

بعد عرض عقدة، يمكنك تعديلها باستخدام محرِّر Drupal. على سبيل المثال، يمكنك تعديل فعل HTTP ووصف واجهة برمجة التطبيقات، أو إضافة طلب بحث جديد أو معلمة عنوان جديدة إلى واجهة برمجة التطبيقات. إِنْتَ تعديل العُقد التي تم إنشاؤها من ملف WADL أو مواصفات OpenAPI، أو العُقد التي يتم إنشاؤها يدويًا.

يمكنك أيضًا تعديل ملف WADL الأصلي أو مواصفات OpenAPI. عندما تنتهي من تحريره واستيراد ملف WADL أو مواصفات OpenAPI مرة أخرى إلى النموذج كمراجعة جديدة، ثم عرض التغييرات ونشرها على النحو الموضَّح أعلاه.

لتعديل عقدة باستخدام محرِّر Drupal:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. انتقِل إلى عقدة Drupal المقابلة لمستندات واجهة برمجة التطبيقات التي تريد الاطّلاع عليها. تعديل.
  3. اختَر تعديل لاستخدام محرِّر Drupal.
  4. بعد اكتمال التعديلات، اختَر تعديل الطريقة.

بدلاً من ذلك، يمكنك تعديل العقدة من نموذج Smart Docs:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. انقر على المحتوى >". Smart Docs في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد تحديثه، حدد مراجعات واجهة برمجة التطبيقات ضمن العمليات.
  4. حدد مراجعة النموذج التي تريد نشرها.
  5. اختَر طريقة التعديل في القائمة المنسدلة العمليات في القائمة المنسدلة طريقة تريد تعديلها.

لحذف عقدة:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. انقر على المحتوى >". Smart Docs في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد تحديثه، حدد مراجعات واجهة برمجة التطبيقات ضمن العمليات.
  4. حدد مراجعة النموذج التي تريد نشرها.
  5. اختَر حذف الطريقة في القائمة المنسدلة العمليات للطريقة.
    تنبيه: يؤدي حذف العُقدة إلى إزالة واجهة برمجة التطبيقات من النموذج أيضًا. إذا كنت فقط إلغاء نشر واجهة برمجة التطبيقات بحيث يتم إخفاؤها عن مستخدمي البوابة، ولكن لا يريدون حذفها من النموذج، يجب إلغاء نشر العُقدة كما هو موضح أعلاه.

تحتوي البوابة على تقرير مدمج يعرض معلومات حول أي عقدة يتم عرضها بواسطة نموذج Smart Docs الذي لم يعد يشير إلى طرق صالحة للنموذج. الوصول إلى التقرير من خلال اختيار التقارير في قائمة Drupal، ثم اختيار التقرير باسم حالة عقدة Smart Docs.

تصدير نموذج واستيراده

تتيح لك أداة Smart Docs تصدير نموذج حالي إلى ملف. على سبيل المثال، يمكنك تحديد الإنتاج وبيئة مرحلية. بعد ذلك، ستُجري جميع تعديلات "مستندات Google" على مراحل محددة. عندما تكون مستعدًا لإصدار واجهات برمجة التطبيقات، يمكنك تصدير النموذج المرحلي واستيراده. في نموذج الإنتاج.

يؤدي استيراد أحد النماذج إلى إنشاء نسخة جديدة من النموذج. تحاول ميزة Smart Docs مطابقة البيانات الحالية واجهات برمجة التطبيقات في النموذج مع واجهات برمجة التطبيقات التي تم استيرادها. في حال رصد Smartالمستندات مطابقة، تُحدِّث عملية الاستيراد منصة Drupal عقدة تتوافق مع واجهة برمجة التطبيقات الحالية. إذا لم يكتشف Smart Docs أي تطابق، عندئذٍ تنشئ عقدة جديدة Drupal لواجهة برمجة التطبيقات.

على سبيل المثال، لديك واجهة برمجة تطبيقات POST تتوافق مع عقدة Drupal برقم التعريف 91. يمكنك حينئذٍ استيراد نموذج، وستكتشف Smart Docs تطابقًا بين واجهة برمجة تطبيقات POST في النموذج الذي تم استيراده بواجهة برمجة التطبيقات الحالية واجهة برمجة تطبيقات POST. عند إجراء أي تعديلات على واجهة برمجة التطبيقات POST، سيتم تعديل عقدة Drupal 91. وإذا لم يكتشف Smartالمستندات مطابقة، سيؤدي ذلك إلى إنشاء عقدة Drupal جديدة بمعرّف جديد.

تُجري Drupal المطابقة باستخدام الخصائص التالية لواجهة برمجة التطبيقات:

  • internalName: اسم النموذج الداخلي
  • httpMethod: طريقة HTTP لواجهة برمجة التطبيقات، مثل: GET أو PUT أو POST أو حذف.
  • resourcePath: مسار المورد.
  • مَعلمات طلب البحث: أيّ مَعلمات طلب بحث تستخدمها واجهة برمجة التطبيقات.

فإذا تطابقت الخصائص الأربع لواجهة برمجة التطبيقات التي تم استيرادها مع واجهة برمجة تطبيقات حالية في النموذج، فعندئذٍ يعدِّل تطبيق Smartالمستندات عقدة Drupal الحالية.

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

  • revisionNumber
  • createdTime
  • modifiedTime
  • apiRevisionId
  • resourceId

لتصدير نموذج:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. اختيار المحتوى > Smart Docs في قائمة إدارة Drupal.
  3. للنموذج الذي تريد تصديره، اختَر تصدير ضمن العمليات.
  4. اختَر نوع ملف التصدير بتنسيق Smart Docs JSON.
  5. انقر على تصدير.
  6. يُطلب منك حفظ الملف على القرص أو فتحه في محرر.

لاستيراد نموذج:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. اختيار المحتوى > Smart Docs في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد استيراده، اختَر استيراد ضمن العمليات.
  4. اختَر Smart Docs JSON في القائمة المنسدلة اختيار تنسيق.
  5. اختَر ملف أو عنوان URL في نوع التحميل:
    1. إذا اخترت ملف، انتقِل إلى ملف JSON.
    2. إذا اختَرت عنوان URL، حدِّد عنوان URL لملف JSON لتطبيق Smart Docs.
  6. انقر على استيراد لاستيراده إلى النموذج.
  7. ستتم إعادة توجيهك إلى صفحة معلومات النموذج حيث يمكنك الآن عرض الأمثل. لاحظ أن عملية الاستيراد تنشئ نسخة جديدة من النموذج.
  8. اعرض العُقد وانشرها.

تعديل نموذج Smart Docs

يحدِّد نموذج Smart Docs كيفية ظهور عُقد Drupal على الشاشة. كل مستند Smart Docs أن يستخدم نفس النموذج الافتراضي أو يمكنك تخصيص النموذج المستخدم نموذج فردي.

يتضمن قالب Smart Docs ملف قالب تم ترميزه كملف Handlebars .hbr وملفات CSS وملفات JavaScript. باستخدام المقاود، يعتمد الكثير من المحتوى على متغيّر باستخدام ميزة تعبيرات المقبض، مثل &123;&123;body}}. قائمة بالعناصر الحالية يتم توفير تعبيرات المقبض في تعليق أعلى الملف. للحصول على معلومات عن باستخدام "المقاود" لتخصيص النماذج، يُرجى الاطّلاع على http://handlebarsjs.com.

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

تحميل صورة مخصّصة ملف نموذج Smartالمستندات

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

إذا كنت ترغب في استخدام ملف نموذج Smartالمستندات الافتراضي كنقطة بداية عند إنشاء ملف نموذج Smart Docs المخصص، يمكنك تنزيل نسخة من: profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr

لتحميل ملف نموذج Smart Docs مخصص:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. حدد التهيئة > Smartالمستندات في Drupal إدارة الموقع.
  3. وسِّع منطقة الإعدادات المتقدمة في الصفحة.
  4. ضمن "تحميل نموذج طريقة مخصّصة"، انقر على اختيار ملف، انتقل إلى ملف Handlebars .hbr.
  5. انقر على تحميل.
  6. انقر على حفظ الإعداد.

جارٍ استعادة ملف نموذج Smartالمستندات التلقائي

يمكنك استعادة ملف نموذج Smartالمستندات التلقائي. بعد استعادة تطبيق Smart Docs التلقائي، عند إنشاء نماذج جديدة أو استيراد واجهات برمجة تطبيقات جديدة إلى الأمثل.

لاستعادة ملف نموذج Smart Docs التلقائي:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. حدد التهيئة > Smartالمستندات في Drupal إدارة الموقع.
  3. وسِّع منطقة الإعدادات المتقدمة في الصفحة.
  4. ضمن "تحميل نموذج طريقة مخصّصة"، انقر على إزالة بجانب قسم ملف نموذج Smart Docs المخصص.
  5. انقر على حفظ الإعداد.

جارٍ التعديل نموذج Smart Docs لنموذج فردي

يمكنك تعديل النموذج المستخدم في نموذج فردي.

لتعديل قالب نموذج فردي:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. اختيار المحتوى > Smart Docs في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد تعديله، اختَر الإعدادات ضمن العمليات.
  4. في منطقة "نموذج الطريقة"، عدِّل القالب حسب الحاجة.
  5. انقر على حفظ النموذج.
  6. تصفَّح للوصول إلى عقدة Drupal. من المفترض أن تظهر لك تغييرات النموذج على الصفحة.

تهيئة نوع مصادقة Smart Docs

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

للحصول على واجهة برمجة تطبيقات آمنة، يتيح Smart Docs أنواع المصادقة التالية:

  • المصادقة الأساسية - تمرير بيانات اعتماد المصادقة الأساسية زوج اسم المستخدم وكلمة المرور. في حال عدم تحديد استخدام OAuth كنوع بيانات اعتماد، ستصبح واجهة برمجة التطبيقات على استخدام المصادقة الأساسية.
  • OAuth 2.0 - يصادق مقدم خدمة تابع لجهة خارجية على بيانات المستخدم تضمن أن المستخدم لديه تفويض لواجهة برمجة التطبيقات، ثم تُصدر إمكانية وصول الرمز المميز. عندما تقدم طلب Smart Docs إلى واجهة برمجة تطبيقات محمية، ينشئ Smart Docs الطلب إرساله إلى مقدم الخدمة. يتحقق مقدم الخدمة بعد ذلك من الرمز المميز ويضمن عدم انتهاء صلاحيته
  • رمز مميّز مخصّص: تمرير قيمة رمز مميّز كعنوان أو مَعلمة طلب بحث إلى كلّ رمز طلبك.

بالنسبة إلى كل نوع من أنواع المصادقة، يمكنك إنشاء مخطط أمان يحدد خصائص المصادقة. على سبيل المثال، لمصادقة الرمز المميز المخصص، نظام الأمان يحدد كيفية تمرير الرمز المميز (الرأس، معلَمة طلب البحث، ومَعلمة النص) واسم الرمز.

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

في ملف WADL، يمكنك تحديد ما إذا كانت واجهة برمجة التطبيقات تتطلب المصادقة باستخدام علامة &lt;apigee:authentication&gt; Apigee، كما كما هو موضح أدناه:

<method id="statusespublic_timeline" name="GET" apigee:displayName="PublicTimeline">
    ...
    <apigee:authentication required="true"/>
</method>

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

يُرجى ملاحظة أنّه لا يمكنك تحديد نوع المصادقة في ملف WADL. يمكنك القيام بذلك عن طريق تعديل العقدة في Drupal. لمزيد من المعلومات عن ملفات WADL، يُرجى الاطّلاع على WADL. المرجع:

في صفحة واجهة برمجة التطبيقات في Drupal، يضيف تطبيق Smartالمستندات الزر التالي للسماح للمستخدمين بتحديد بيانات اعتماد المصادقة الأساسية:

إذا عدّلت العقدة لضبط نوع المصادقة على OAuth، فسيضيف Smart Docs الزر التالي إلى الصفحة:

بالنسبة إلى الرمز المميّز المخصّص، تضيف ميزة Smart Docs ما يلي:

جارٍ الإعداد مصادقة أساسية

إذا كنت تستخدم المصادقة الأساسية مع واجهة برمجة التطبيقات، ما عليك سوى تحديد علامة &lt;apigee:authentication&gt; في WADL. ملف تستخدمه لإنشاء النموذج.

لتطبيق المصادقة الأساسية على الطرق التي تم إنشاؤها من مصدر آخر غير ملف WADL:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. انقر على المحتوى >". Smart Docs في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج المطلوب، حدد مراجعات واجهة برمجة التطبيقات ضمن العمليات.
  4. بالنسبة إلى مراجعة النموذج التي تريد تعديلها، حدد الأمان الإعدادات ضمن العمليات.
  5. اختَر إضافة مخطط أمان.
  6. حدِّد اسم نظام الأمان.
  7. اختَر أساسي على أنّه النوع.
  8. اختَر إرسال.
  9. بالنسبة إلى كل طريقة في النموذج، عدِّل الطريقة لضبط مخطط الأمان الخاص بها. إلى المخطط الأساسي.
    1. انقر على المحتوى >". Smart Docs في قائمة إدارة Drupal.
    2. بالنسبة إلى النموذج المطلوب، حدد مراجعات واجهة برمجة التطبيقات ضمن العمليات.
    3. بالنسبة إلى مراجعة النموذج التي تريد تعديلها، حدد مراجعة التفاصيل ضمن العمليات.
    4. اختَر طريقة التعديل لواجهة برمجة التطبيقات التي تريد تعديلها.
    5. اختَر مخطط الأمان لواجهة برمجة التطبيقات.
    6. احفظ واجهة برمجة التطبيقات.

جارٍ الإعداد مصادقة OAuth 2.0

يمكنك ضبط نموذج لاستخدام OAuth 2.0 في Smart Docs، بدلاً من النموذج التلقائي بدلاً من بروتوكول OAuth 2.0 الأساسي. المصادقة. يمكنك تهيئة OAuth في مكانين:

  1. إنشاء مخطط أمان لكل مراجعة نموذج ضمن الأمان إعدادات النسخة السابقة.
  2. حدد معرف العميل وسر العميل لجميع مراجعات النموذج ضمن إعدادات الطراز.

لتفعيل بروتوكول OAuth:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. انقر على المحتوى >". Smart Docs في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج المطلوب، اختَر مراجعات واجهة برمجة التطبيقات ضمن "العمليات".
  4. بالنسبة إلى مراجعة النموذج التي تريد تعديلها، اختَر إعدادات الأمان ضمن العمليات.
  5. اختَر إضافة مخطط أمان.
  6. حدِّد اسم نظام الأمان.
  7. اختَر OAuth 2.0 بصفته النوع.
  8. حدِّد نوع المنح.
  9. أدخِل القيم في حقول عنوان URL للتفويض. الترخيص يتم استخدام عنوان URL للحصول على رمز الدخول.
  10. يجب ضبط فعل التفويض على GET أو POST.
  11. أدخِل عنوان URL لرمز الدخول. عنوان URL لرمز الدخول هو عنوان URL المستخدم استبدال رمز الطلب برمز الدخول.
  12. أدخِل اسم معلَمة رمز الدخول.
  13. استخدِم In لتحديد كيفية تمرير الرمز المميّز: Header، طلب البحث أو النص الأساسي.
  14. اضبط نطاقات OAuth.
  15. اختَر إرسال.
  16. انقر على المحتوى >". Smart Docs في قائمة إدارة Drupal.
  17. بالنسبة إلى الطراز، اختَر الإعدادات في العمليات. الجديد.
  18. أدخِل القيم في حقلَي Client-ID (رقم تعريف العميل) وClient (العميل). سرّي:
  19. اختَر حفظ إعدادات مصادقة النموذج.
  20. بالنسبة إلى كل طريقة في النموذج، عدِّل الطريقة لضبط مخطط الأمان الخاص بها. إلى مخطط أمان OAuth.
    1. انقر على المحتوى >". Smart Docs في قائمة إدارة Drupal.
    2. بالنسبة إلى النموذج المطلوب، حدد مراجعات واجهة برمجة التطبيقات ضمن العمليات.
    3. بالنسبة إلى مراجعة النموذج التي تريد تعديلها، حدد مراجعة التفاصيل ضمن العمليات.
    4. اختَر طريقة التعديل لواجهة برمجة التطبيقات التي تريد تعديلها.
    5. اختَر مخطط الأمان لواجهة برمجة التطبيقات.
    6. احفظ واجهة برمجة التطبيقات.

إعداد مصادقة الرموز المميّزة المخصّصة

يمكنك ضبط نموذج لاستخدام مصادقة الرمز المميز المخصص.

لتفعيل الرموز المميّزة المخصّصة:

  1. سجِّل الدخول إلى البوابة كمستخدم لديه امتيازات المشرف أو امتياز إنشاء المحتوى.
  2. انقر على المحتوى >". Smart Docs في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج المطلوب، حدد مراجعات واجهة برمجة التطبيقات ضمن العمليات.
  4. بالنسبة إلى مراجعة النموذج التي تريد تعديلها، حدد الأمان الإعدادات ضمن العمليات.
  5. اختَر إضافة مخطط أمان.
  6. حدِّد اسم نظام الأمان.
  7. اختَر Apikey باعتباره النوع.
  8. اضبط اسم مَعلمة التي تحتوي على الرمز المميّز.
  9. استخدم In لتحديد كيفية تمرير الرمز المميّز: العنوان وطلب البحث أو Body.
  10. اختَر إرسال.
  11. بالنسبة إلى كل طريقة في النموذج، عدِّل الطريقة لضبط مخطط الأمان الخاص بها. مخطط الرمز المميز.
    1. انقر على المحتوى >". Smart Docs في قائمة إدارة Drupal.
    2. بالنسبة إلى النموذج المطلوب، حدد مراجعات واجهة برمجة التطبيقات ضمن العمليات.
    3. بالنسبة إلى مراجعة النموذج التي تريد تعديلها، حدد مراجعة التفاصيل ضمن العمليات.
    4. اختَر طريقة التعديل لواجهة برمجة التطبيقات التي تريد تعديلها.
    5. اختَر مخطط الأمان لواجهة برمجة التطبيقات.
    6. احفظ واجهة برمجة التطبيقات.

حذف نموذج

عند حذف أحد النماذج (المحتوى > Smart Docs، انقر على حذف في حقل العمليات في Drupal)، يتم حذف النموذج من مؤسسة Edge. هذا يعني أنه إذا البوابات الأخرى تشير إلى النموذج، فإن النموذج لم يعد متاحًا. لمزيد من المعلومات راجِع لمحة عن نماذج SmartDoc ونماذجها.