שימוש ב-SmartDocs לתיעוד ממשקי API

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

עם SmartDocs תוכלו לתעד את ממשקי ה-API שלכם בפורטל המפתחים של Drupal 7, בדרך ש מאמרי העזרה של ה-API אינטראקטיביים לגמרי. המשמעות של תיעוד אינטראקטיבי היא שמשתמשי הפורטל יכולים:

  • מידע על ממשקי ה-API
  • שליחת בקשה פעילה ל-API
  • הצגת תשובה פעילה שהוחזרה מה-API

יצירת תיעוד אינטראקטיבי על ממשקי ה-API שלכם מאפשרת למשתמשי הפורטל לעשות בקלות ללמוד, לבדוק ולהעריך את ממשקי ה-API שלכם.

הממשק Edge management API הוא API ל-RESTful שמאפשר לגשת לשירותי API באמצעות צד הלקוח ב-HTTP. ב-Apigee משתמשים ב-SmartDocs כדי ליצור מסמכים אינטראקטיביים לניהול Edge API. תוכלו למצוא כאן את מסמכי התיעוד של ה-API.

דוגמה לפורטל SmartDocs

כדי להשתמש ב-SmartDocs, צריך פורטל שירותים למפתחים של Apigee. מידע נוסף זמין במאמר הבא: יצירת מפתח .

בדף הבית של פורטל המפתחים, לוחצים על APIs בסרגל הניווט העליון כדי להציג את הדף 'מסמכי תיעוד של ה-API'.

יש שני ממשקי API מתועדים בפורטל: Hello World ו-Pet Store Example.

ממשק ה-API של Hello World נוצר מ-OpenAPI המדמה את היעד מפרט, mocktarget.yaml. מידע נוסף זמין בכתובת https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.

ה-pet Store Example API נוצר מההדגמה הקלאסית של חנות חיות המחמד.

נעים להכיר: Hello World API:

  1. לוחצים על Hello World API. דף הסיכום של Hello World API מוצג:
  2. לוחצים על View API Validation. מסמך SmartDocs עבור משאב זה מוצגות:
  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. לוחצים על הכרטיסייה Request כדי להציג את הבקשה, או על cURL. כדי להציג את קריאת ה-cURL המתאימה.

איך לתעד את ממשקי ה-API באמצעות SmartDocs

SmartDocs מייצג את ממשקי ה-API שלכם באמצעות מודל, שבו המודל מכיל את כל על ממשקי ה-API שלכם. הפורטל שולף מידע על ממשקי ה-API שלכם מהמודל כדי לעבד את דפי התיעוד בפורטל כצמתים של Drupal, כאשר כל צומת של Drupal תואם לדף של תיעוד בפורטל.

השלבים הכלליים שצריך לבצע כדי להשתמש ב-SmartDocs הם:

  1. מגדירים את המודול של Drupal SmartDocs בפורטל.
  2. יצירת מודל SmartDocs.
  3. הוספת ממשקי API למודל מקובץ WADL, OpenAPI (לשעבר Swagger) או באופן ידני.
  4. לעבד את המודל כאוסף של צמתים של Drupal. כל צומת של Drupal שכולל מידע על ממשק API יחיד. לדוגמה, אם משאב ב-API תומך בשני סוגי המפתחות ב-POST ובבקשת PUT, SmartDocs יוצר צומת Drupal נפרד ל-POST ול-PUT.
  5. מפרסמים את הצמתים של Drupal. לאחר הפרסום, משתמשי הפורטל יוכלו להציג לקיים אינטראקציה עם ה-API.
  6. לערוך את צמתים של Drupal, לפני או אחרי הפרסום שלהם. אפשר לערוך את צומתי ה-Drupal באמצעות עורך Drupal או לערוך את קובץ ה-WADL המקורי. מפרט OpenAPI. כשמסיימים לערוך את קובץ ה-WADL או את מפרט OpenAPI, מייבאים להחזיר אותו למודל כגרסה חדשה, ואז לעבד ולפרסם את השינויים.
  7. מפעילים TLS. מפני ש-SmartDocs יכול לשלוח פרטי כניסה לאימות בקצה העורפי במסגרת שליחת בקשה לממשקי ה-API, צריך להפעיל TLS בפורטל כדי כדי לוודא שפרטי הכניסה האלה מאובטחים. בסביבות הייצור והבדיקה של הפורטל, Apigee מספקת את אישור ה-TLS שנדרש כדי לשלוח בקשות https:// . אבל לפני שאתם מתחילים באתר שלכם, עליכם לקבל אישור TLS משלכם ולהפעיל TLS. מידע נוסף זמין במאמר שימוש ב-TLS ב-TLS .

מידע על מודלים ותבניות של SmartDoc

כשיוצרים מודל בפורטל, הוא נשמר בפועל ב-Edge לא ב-Drupal. מודל הוא בלוק גדול של JSON עם שם פנימי (כמו my-smartdocs-api), והיא מגדירה את המבנה של API. מצד שני, הפורטל שלכם מעבד את המודל ב-HTML ומספק ממשק עריכה למודל. עדכונים ב-API בפורטל, מועברים באופן אוטומטי חזרה למודל המקור.

מאוחסן בארגון

מאוחסן ב-Drupal

דגמים

תבניות

צמתים של Drupal עם פונקציונליות עריכה

נניח שיש לכם בארגון מספר פורטלים (לדוגמה: dev, שלב ו- לסביבת הייצור). בפנתיאון, אתם מעבירים פורטל מסביבה אחת לאחרת. כל מופע של נראה שהוא מכיל מודל משלו אבל כולם באמת מתייחסים למקור מודל טרנספורמר. אם עורכים את ה-API בפיתוח, המודל מתעדכן והשינויים יופיעו בסביבת הייצור. בדומה לכך, אם מוחקים מודל בפיתוח, המקור נמחק והוא לא זמין יותר בסביבת הייצור.

התבניות שולטות במראה ובתחושה של מסמכי SmartDocs והתבניות האלו (שמנוהלות על ידי כידונים וקובצי CSS) נשמרים עם כל מופע של הפורטל. כך שכל פורטל יכול מבחינה תיאורטית להשתמש בתבנית ייחודית לכל מודל. אבל אחת מהנוחות של מסגרת הרינדור היא שתבנית ברירת מחדל (ברירת המחדל של Apigee או תבנית שמספקים) מועברת באופן אוטומטי שמיושמות בכל מודל.

בתרשים הבא מוצג הקשר בין מודלים ופורטלים. החיצים הירוקים מוצגים סנכרון אוטומטי.

פקודת cURL הבאה מציגה רשימה של כל המודלים בארגון שלך:

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

הגדרת מודול SmartDocs

Apigee הטמיעה את SmartDocs כמודול Drupal מותאם אישית. יש לבצע את התהליך הבא כדי להגדיר את מודול SmartDocs.

כדי להגדיר את מודול SmartDocs:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. בוחרים באפשרות מודולים בתפריט הניהול של Drupal. הרשימה של כל ההודעות יופיעו המודולים של Drupal שהותקנו.
  3. מפעילים את מודול SmartDocs.
  4. שומרים את ההגדרות האישיות.
  5. בוחרים באפשרות מודולים בתפריט הניהול של Drupal.
  6. בוחרים באפשרות SmartDocs -> הרשאות ולוודא ש'מבצעים ניהול' משימות למודול SmartDocs בשביל 'מנהל' התפקיד מופעל.
  7. בוחרים באפשרות הגדרה > Dev Portal בניהול של Drupal תפריט
  8. מגדירים את הזמן הקצוב לתפוגה של חיבור ואת הזמן הקצוב לתפוגה של בקשה ל-16 שניות.
  9. שומרים את ההגדרות האישיות.
  10. קובעים את ההגדרות של כתובות ה-URL:
    1. בוחרים באפשרות הגדרה > חיפוש ומטא-נתונים > כתובות URL חלופיות > הגדרות בתפריט Drupal.
    2. מגדירים את אורך הכינוי המקסימלי ואת הרכיב המקסימלי האורך ל-255.
    3. מרחיבים את הקטע פיסוק.
    4. לסוגריים מסולסלים שמאליים ({) ולסוגריים מסולסלים ימניים (}) הגדרות, בוחרים באפשרות ללא פעולה (אין להחליף).
    5. לוחצים על Save configuration (שמירת ההגדרות האישיות).
  11. אם פורטל המפתחים יהיה גלוי למשתמשים ברשת פנימית ללא גישה אל באינטרנט, או אם קבוצת משנה של ממשקי ה-API שלכם פונה לרשת פרטית, מגדירים את SmartDocs API כתובת ה-URL של שרת ה-proxy, באופן הבא:
    1. בוחרים באפשרות הגדרה > SmartDocs בניהול של Drupal תפריט
    2. הרחב את הגדרות מתקדמות.
    3. מעדכנים את השדה כתובת URL של שרת proxy של SmartDocs באופן הבא: <host>/smartdocs/v1/sendrequest.
      העזרה המוטבעת אמורה לספק את הערך הנדרש לסביבה. לדוגמה:
      https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest

      ערך ברירת המחדל של השדה הזה הוא https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest
    4. לוחצים על Save configuration (שמירת ההגדרות האישיות).

יצירת מודל

מודל מכיל את כל המידע על הייצוג של ה-API. אפשר להגדיר מספר מודלים בפורטל לתמיכה בממשקי API שונים, או לקבץ את כל ממשקי ה-API מודל טרנספורמר.

כל מודל מציין שם פנימי ייחודי שמגדיר גם את כתובת ה-URL הבסיסית של נוצרו צמתים של Drupal. כתובת ה-URL של כל צומת של Drupal מופיעה בצורה הבאה:

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

איפה:

  • drupalBasePath: כתובת ה-URL הבסיסית של הפורטל.
  • internalName: השם הפנימי של המודל.
  • httpMethod: שיטת ה-HTTP של ה-API, למשל: get, Put, post או מחיקה.
  • resourcePath: נתיב המשאב.

לדוגמה, אם ציינתם את השם הפנימי כ-'mymodel', אז כתובת ה-URL עבור המודל שנוצר צומת Drupal לבקשת GET למשאב בשם ' /books' היא:

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

כדי ליצור מודל

כשיוצרים מודל, הוא מאוחסן בארגון Edge בתור המקור של ה-API שלנו. למידע נוסף, ראו מידע על מודלים של SmartDoc וכן תבניות.

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. בוחרים באפשרות תוכן > SmartDocs בניהול של Drupal תפריט
  3. בוחרים באפשרות מודל חדש בחלק העליון של הדף.
  4. ממלאים את השדות הבאים:
    • שם: שם המודל שיוצג בכל האתר.
    • שם פנימי: תוך כדי שמקלידים את השם, מוצגים השמות. השם הפנימי של המודל חייב להיות ייחודי בכל המודלים. השם הפנימי חייב להכיל רק אותיות קטנות, מספרים ומקפים, ללא רווחים. לוחצים על עריכה כדי לערוך את השם הזה.
    • תיאור: תיאור של המודל.
  5. בוחרים באפשרות יצירת מודל.

אחרי יצירת המודל, תופנו לדף של המודל. משם, אפשר להשתמש התפריט הנפתח 'פעולות' ב-BX כדי:

  • ייבוא קובץ WADL שמתאר את ה-API או ציון כתובת ה-URL של OpenAPI מפרט שמתאר את ה-API שלכם.
  • הוספת גרסה למודל
  • לשנות את ההגדרות של המודל, כולל גיליונות הסגנונות שבהם נעשה שימוש מודל טרנספורמר.
  • ייצוא המודל לקובץ.
  • מחיקת המודל.

הוספת ממשקי API למודל

אפשר להוסיף ממשקי API למודל בדרכים הבאות:

  • ייבוא קובץ WADL שמכיל את הגדרת ה-API
  • ייבוא מפרט OpenAPI (OpenAPI 2.0 או 1.2)
  • יצירה ידנית של משאבים ושיטות

אפשר גם לייבא קובץ JSON של SmartDocs אל המודל. בדרך כלל נוצר הקובץ ראשית, ייצוא מודל קיים, עריכת הקובץ ואז ייבוא העדכונים. לקבלת מידע נוסף, מידע נוסף מופיע בקטע ייצוא וייבוא של מודל. שלמטה.

סרטון: לצפייה בסרטון קצר שבו מוסבר איך מוסיפים ממשקי API למודל SmartDocs ייבוא מפרט OpenAPI.

ייבוא של WADL

אחרי שיוצרים מודל, צריך לייבא קובץ WADL שמתאר את ה-API. הכול כאשר מייבאים קובץ WADL, יוצרים באופן אוטומטי גרסה חדשה של המודל.

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. בוחרים באפשרות תוכן > מסמכים חכמים ב-Drupal תפריט ניהול.
  3. בוחרים את המודל שרוצים לעדכן.
  4. בקטע פעולות, בוחרים באפשרות ייבוא.
  5. בוחרים באפשרות WADL בתפריט הנפתח Choose Format (בחירת פורמט) שבתפריט הנפתח. דף הייבוא של SmartDocs.
  6. בוחרים קובץ או כתובת אתר בהעלאה התפריט הנפתח.
    1. אם בוחרים באפשרות קובץ, עוברים אל קובץ ה-WADL.
    2. אם בוחרים באפשרות כתובת URL, צריך לציין את כתובת ה-URL של קובץ ה-WADL.
  7. לוחצים על ייבוא כדי לייבא אותו למודל. מעכשיו אפשר לעבד את המודל.
  8. תועברו לדף הפרטים של המודל, שבו תוכלו לעבד את מודל טרנספורמר.

ייבוא OpenAPI מפרט

אחרי שיוצרים מודל בהצלחה, אפשר לייבא OpenAPI (לשעבר Swagger) מפרט. Edge תומך ב-OpenAPI בגרסאות 1.2 ו-2.0.

OpenAPI משתמש בקבצים שמכילים אובייקטים של JSON כדי לתאר API. בכל פעם שמבצעים ייבוא למפרט OpenAPI, יוצרים באופן אוטומטי גרסה חדשה של המודל.

כדי לייבא מפרט OpenAPI:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. יש לבחור באחת מהאפשרויות הבאות תוכן > SmartDocs תפריט ניהול של Drupal.
  3. בוחרים את המודל שרוצים לעדכן.
  4. בקטע פעולות, בוחרים באפשרות ייבוא.
  5. בוחרים באפשרות Swagger JSON או Swagger YAML בתפריט הנפתח Choose Format (בחירת פורמט), בדף הייבוא SmartDocs.
  6. בוחרים באפשרות קובץ או כתובת URL התפריט הנפתח Upload Type (צריך לבחור באפשרות URL כדי לעבור ל-OpenAPI 1.2).
    1. אם בוחרים באפשרות File, מעיינים אל OpenAPI מפרט.
    2. אם בוחרים באפשרות כתובת URL, צריך לציין את כתובת ה-URL של ה-OpenAPI מפרט.
  7. לוחצים על ייבוא כדי לייבא אותו למודל.
  8. תועברו לדף הפרטים של המודל, שבו תוכלו לעבד את מודל טרנספורמר.

יצירת משאבים באופן ידני וה-methods

אם אין לכם קובץ WADL או מפרט OpenAPI שמייצגים את ה-API, תוכלו להוסיף ממשקי API למודל באופן ידני. כמו כן, אם משתמשים בקובץ WADL או במפרט OpenAPI כדי ליצור תוכלו להשתמש בתהליך הזה כדי לערוך את ממשקי ה-API, כולל הוספת ממשקי API חדשים, ייבוא.

כדי להוסיף API באופן ידני:

  1. ליצור גרסה חדשה של המודל.

    כשיוצרים את הגרסה הקודמת, צריך לציין את הנתיב הבסיסי היחיד לכל ממשקי ה-API במודל, כלומר, כל ממשקי ה-API במודל חולקים אותו נתיב בסיס. לדוגמה, מציינים את הנתיב הבסיסי כ:

    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 מוגדרות במשאב אחד ב-SmartDocs.

ככלל אצבע:

  • ליצור מודל SmartDocs שונה לכל נתיב בסיס ייחודי ב-API.
  • להגדיר משאב SmartDocs נפרד לכל משאב ייחודי ב-API.
  • להגדיר שיטת SmartDocs שונה לכל פועל של HTTP שנתמך על ידי משאב.

יצירת גרסה חדשה של מודל

אפשר להוסיף משאב רק לגרסה קיימת של מודל. אם למודל כבר יש כדי להוסיף את המשאב. אם המודל חדש ואין לו שינויים, יש ליצור מודל חדש גרסה קודמת.

כדי ליצור גרסה חדשה של מודל:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. יש לבחור באחת מהאפשרויות הבאות תוכן > SmartDocs ב- תפריט הניהול של Drupal.
  3. בוחרים באפשרות הוספת גרסה עבור המודל שרוצים לעדכן. בקטע פעולות.
  4. בדף Add API Revision, מזינים את הפרטים הבאים:
    • שם תצוגה: שם הגרסה הקודמת כפי שהוא מופיע בפורטל.
    • מזהה גרסה: מזהה קצר של הגרסה הקודמת.
    • תיאור: תיאור של הגרסה הקודמת.
    • כתובת URL בסיסית: כתובת ה-URL הבסיסית של כל ממשקי ה-API בגרסת המודל. א' יכול להשתמש בכתובות אתרים בסיסיות שונות לכל גרסה. לדוגמה, מציינים גרסה בכתובת האתר הבסיסית. עבור הגרסה הראשונה של המודל, כתובת ה-URL הבסיסית היא:
      https://myCompany.com/v1
      בגרסה הקודמת, כתובת ה-URL הבסיסית יכולה להיות:
      https://myCompany.com/v2
  5. בוחרים באפשרות הוספת גרסה. אתם תועברו לדף הגרסאות של המודל. עכשיו אפשר להגדיר משאבים במודל.

הגדרת משאב

משאב מציין את כתובת ה-URL המלאה של ממשק API. כשמגדירים משאב, צריך לציין נתיב המשאב, שמשולב עם כתובת ה-URL הבסיסית בגרסה של המודל כדי ליצור את כתובת ה-URL המלאה של המשאב.

כדי להגדיר משאב:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. יש לבחור באחת מהאפשרויות הבאות תוכן > SmartDocs ב- תפריט הניהול של Drupal.
  3. בקטע פעולות, עבור המודל שרוצים לעדכן, בוחרים באפשרות API תיקונים להצגת כל הגרסאות של מודל.
  4. בוחרים גרסה קודמת כדי לערוך.
  5. בדף הגרסה הקודמת, בוחרים באפשרות הוספת משאב מהתפריט הנפתח.
  6. בדף Add Resource (הוספת משאב), מזינים את הפרטים הבאים:
    • Display Name: שם המשאב.
    • נתיב: נתיב המשאב, שמתחיל ב-'/'. הערך של השדה Path משולב עם כתובת ה-URL הבסיסית של גרסת המודל. כדי ליצור את כתובת ה-URL המלאה של המשאב.
    • Description: תיאור של המשאב.
    • פרמטרים: אפשר להזין את אובייקט ה-JSON שמגדיר כל פרמטר. במשאב. הפרמטרים האלה מתוארים בהמשך.
  7. בוחרים באפשרות Add Resource (הוספת משאב). אתם מועברים לדף המודל. מעכשיו אפשר להגדיר methods במשאב.

אפשר גם להוסיף פרמטרים למשאב, כמו תבנית, שאילתה וכותרת . כל הפרמטרים של המשאב עוברים בירושה לכל ה-method שמוגדר במשאב הזה. לכן, אם מגדירים פרמטר של שאילתה במשאב, כל השיטות מתווספות לאותו משאב צריך לתמוך בפרמטר השאילתה.

לחלופין, אפשר להגדיר פרמטרים באמצעות method. לדוגמה, שיטת POST עשויה לתמוך פרמטרים של שאילתה שאינם נתמכים על ידי שיטת DELETE. לכן, מוסיפים פרמטרים ספציפיים לשיטה כשמגדירים את ה-method, כפי שמתואר בהמשך.

התמונה הבאה מראה דף SmartDocs קיים עבור API לאישור או ביטול של מפתח אפליקציות ב-Apigee כשכל סוג פרמטר מודגש:

כל סוג פרמטר מוגדר על ידי אובייקט JSON:

סוג

אובייקט JSON

הערות

תבנית

{
"dataType": "string",
"defaultValue": "",
"description": "The Organization name.",
"name": "org_name",
"required": true,
"type": "TEMPLATE"
}

תמיד חייבים לציין פרמטרים של תבניות, לכן צריך להגדיר את הפרמטר required (חובה) כ-true ולהשמיט את הערך הבא: defaultValue

הערך description מופיעה בחלון קופץ כשהמשתמש מעביר את העכבר מעל כתובת ה-URL בדף SmartDocs.

שאילתה

{
"dataType": "string",
"defaultValue": "",
"description": "The location.",
"name": "w",
"required": true,
"type": "QUERY"
}

בפרמטרים הנדרשים של השאילתה עדיין אפשר לציין defaultValue, אבל לעיתים קרובות לא.

לפרמטרים אופציונליים של שאילתות, מגדירים את הערך required (חובה) כ-false ומציינים ערך של defaultValue

שם

{
"dataType": "string",
"defaultValue": "application/json",
"description": "ציון בתור <code>application/json</code>.",
"name": "Content-Type",
"required": true,
"type": "gtin"
}

שימו לב איך אפשר להשתמש בתגי 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}

בדף SmartDocs API, המשתמש חייב לערוך את כתובת ה-URL ולציין את החלק org_name ו-developer_email של כתובת האתר לפני כן הם יכולים לשלוח בקשה.

הגדרת שיטה

מגדירים שיטה אחת או יותר לכל משאב. הגדרת השיטה מציינת פועל של HTTP שאפשר להפעיל במשאב. אפשר להגדיר משאב באמצעות method אחת, או בכמה שיטות.

כחלק מהגדרת השיטה, מציינים את כל הפרמטרים שבהם השיטה משתמשת, כולל שאילתה פרמטרים של כותרת. בתיאור שלמעלה מוסבר על הוספת פרמטרים לשיטה מסוימת.

בתמונה הבאה מוצג דף SmartDocs קיים של ממשק ה-API מסוג Create Developer של Apigee עם כל אזור בדף מודגש בערך המתאים שהגדרת כשהגדרת method:

בתמונה הבאה מוצג אותו הדף, אבל נבחר התיאור של גוף הבקשה:

כדי להגדיר method:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. יש לבחור באחת מהאפשרויות הבאות תוכן > SmartDocs ב- תפריט הניהול של Drupal.
  3. בקטע פעולות, עבור המודל שרוצים לעדכן, בוחרים באפשרות API תיקונים להצגת כל הגרסאות של מודל.
  4. בוחרים גרסה קודמת כדי לערוך.
  5. בדף הגרסאות, בוחרים באפשרות הוספת שיטה מהתפריט הנפתח עבור אחת מהאפשרויות את המשאבים.
  6. בדף Edit Method (שיטת העריכה), מזינים את הפרטים הבאים:
    • Display Name: שם ה-API, שהופך גם לכותרת של ה- דף Drupal של ה-API.
    • Description: תיאור ה-API.
    • method Verb: סוג פועל של HTTP.
    • סכימות אבטחה: מציין את מצב האימות, אם קיים, עבור . למידע נוסף, ראו הגדרת אימות SmartDocs .
    • סוג התוכן: סוג התוכן של הבקשה והתגובה. לצפייה שבהמשך על הגדרה של שיטות אימות שונות.
    • פרמטרים: (אופציונלי) כל פרמטר של שאילתה או כותרת ל-method. בתיאור שלמעלה מוסבר איך מוסיפים פרמטר למשאב, כדי לקבל מידע נוסף.
    • מסמכים בגוף הבקשה: (אופציונלי) תיאור גוף הבקשה. פרסום ו-methods PUT מקבלות גוף בקשה. אפשר להשתמש באזור הזה כדי לתאר אותו. אם משמיטים את הערך בערך, לא מופיע הקישור תיאור בקטע גוף הבקשה מדף SmartDocs שנוצר.
    • דוגמה לגוף הבקשה: (אופציונלי) הצגת דוגמה לגוף הבקשה, בדרך כלל כאובייקט JSON או כ-XML. עבור פעלים POST ו-PUT, הפונקציה Request Body דוגמה מועברת כחלק מכל בקשה. משתמשי דף SmartDocs עורכים את המסמך הזה לפני שהם שולחים בקשה ל-API. אם משמיטים את הערך הזה, הקישור Value מתחת לגוף הבקשה לא מופיע דף SmartDocs שנוצר.
    • תגים: מערך של תגים שמשויכים ל-API. ב-SmartDocs משתמשים בתגים כדי לקבץ יחד ממשקי API דומים. לדוגמה, ניתן להחיל את התג 'נתונים סטטיסטיים' לכל ממשקי ה-API על סטטיסטיקה. אפשר לקבץ ממשקי API ממשאבים שונים בתג אחד. אם הם בכולם משתמשים באותו תג.
  7. בוחרים באפשרות הוספת שיטה. אתם מועברים לדף המודל. מעכשיו אפשר לעבד ולפרסם את השיטה.

עיבוד של מודל

אחרי שמוסיפים ממשקי API למודל, אפשר לעבד את המודל. הרינדור ממיר את המודל תיאור של ה-API לצמתים של Drupal. בסיום העיבוד, יוצג לכם פריט Drupal אחד עבור כל API, שבו כל צומת של Drupal תואם לדף HTML.

ניתן לבחור לעבד את המודל כולו בבת אחת, או לבחור ממשקי API נפרדים עבור ברינדור.

כדי לעבד מודל:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. יש לבחור באחת מהאפשרויות הבאות תוכן > SmartDocs ב- תפריט הניהול של Drupal.
  3. למודל שרוצים לעבד, בוחרים באפשרות API Revisions בקטע תפעול.
  4. בוחרים את הגרסה הקודמת שרוצים לעבד. ניתן לעבד צמתים רק מגרסה אחת של את המודל.
  5. בוחרים את השיטות לעיבוד.
  6. בוחרים באפשרות Render Nodes בקטע Update התפריט הנפתח options.
  7. לוחצים על עדכון.
  8. יופיע מסך טעינה שמציג את ההתקדמות בעיבוד הצמתים שהגדרתם.
    לאחר עיבוד הצמתים, המזהה של צומת ה-Drupal של כל API יופיע מתחת שיוך הצומת במודל. לוחצים על הקישור שבצומת שיוך כדי לראות את הצומת שעבר רינדור.

במקום לבחור באפשרות רינדור צמתים,אפשר לבחור באפשרות רינדור ולפרסם צמתים כדי לעבד את ממשקי ה-API ולפרסם אותם מיד כצומת של Drupal.

פרסום צמתים

צומת לא גלוי למשתמשים בפורטל עד שמפרסמים אותו. אפשר לבחור לפרסם צמתים בתהליך הרינדור. אם תבחרו שלא לפרסם את הצמתים, תצטרכו לפרסם אותם באופן ידני בסיום העיבוד.

כדי לפרסם צומת:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. יש לבחור באחת מהאפשרויות הבאות תוכן > SmartDocs ב- תפריט הניהול של Drupal.
  3. למודל שרוצים לפרסם, בוחרים באפשרות API Revisions בקטע תפעול.
  4. בוחרים את הגרסה הקודמת שרוצים לפרסם. אפשר לפרסם צמתים רק מגרסה אחת של המודל.
  5. בוחרים את השיטות לפרסום.
  6. צריך לבחור את הצמתים בגרסה הקודמת שרוצים לפרסם.
  7. בוחרים באפשרות Publish Nodes (פרסום צמתים) מתוך Update התפריט הנפתח options.
  8. לוחצים על עדכון.
  9. כדי לנווט לצומת, בוחרים את מזהה הצומת בקטע שיוך הצומת עמודה.

כברירת מחדל, כתובת ה-URL של Drupal לצומת API שפורסמה היא: http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>. כדי לשלוט בצורה של כתובת ה-URL, יש לפעול לפי התהליך הבא:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. בוחרים באפשרות הגדרה > חיפוש ומטא-נתונים > כתובות URL חלופיות > תבניות בתפריט הניהול של Drupal.
  3. בקטע קו ביטול נעילה לכל הנתיבים של שיטות SmartDocs, מציינים איך רוצים אנחנו יוצרים את הנתיב.
  4. בוחרים באפשרות Save configuration (שמירת ההגדרות האישיות).

בגלל שמירה במטמון בפורטל, ייתכן שדפי המודל לא יופיעו מיד אחרי שמפרסמים אותם. במקרה הצורך, ניתן לנקות באופן ידני את מטמון ה-HTML של SmartDocs באמצעות את התהליך הבא:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. בוחרים באפשרות הגדרה > SmartDocs בניהול של Drupal תפריט
  3. לוחצים על יצירה מחדש של מטמון המודלים של SmartDocs.

ביטול פרסום של צומת

בכל שלב אפשר לבטל את הפרסום של צומת שפורסם. ביטול הפרסום של צומת הופך אותו לבלתי נראה משתמשי הפורטל.

כדי לבטל את הפרסום של צומת:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. יש לבחור באחת מהאפשרויות הבאות תוכן > SmartDocs ב- תפריט הניהול של Drupal.
  3. למודל שרוצים לבטל את הפרסום שלו, בוחרים באפשרות API Revisions בקטע תפעול.
  4. בוחרים את גרסת המודל של הצומת שרוצים לבטל את הפרסום שלו.
  5. בוחרים את הצמתים בגרסה הקודמת שרוצים לבטל את הפרסום שלהם.
  6. בוחרים את הצמתים Unpublish (ביטול הפרסום) מתוך Update (עדכון). התפריט הנפתח options.
  7. לוחצים על עדכון.

הצגת הגרסה הקודמת של מודל

יוצרים גרסה חדשה של מודל על ידי ייבוא קובץ WADL חדש או מפרט OpenAPI במודל קיים או על ידי יצירה ידנית של גרסה חדשה. לאחר יצירת הגרסה החדשה, אפשר לעבד ולפרסם את הגרסה, שתחליף את צומתי ה-Drupal הנוכחיים שפורסמו.

אפשר לעבד ולפרסם צמתים מכמה גרסאות בו-זמנית. כלומר, אם יש לכם חמש גרסאות של מודל, אפשר לפרסם צמתים מכל גרסה קודמת, או מכולם. עם זאת, פרסום API במודל אחד שזהה לצומת שפורסם ממודל אחר מבטל את הפרסום של המודל הישן של ה-API ומחליפה אותה בגרסה האחרונה שפורסמה API.

כדי לראות את הגרסה הקודמת של מודל:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. יש לבחור באחת מהאפשרויות הבאות תוכן > SmartDocs ב- תפריט הניהול של Drupal.
  3. למודל שרוצים לעדכן, בוחרים באפשרות API Revisions בקטע תפעול.
  4. בוחרים את הגרסה הקודמת של המודל שרוצים להציג.
  5. עיבוד ופרסום הצמתים כפי שמתואר למעלה.

עריכת צומת

אחרי עיבוד צומת אפשר לערוך אותו באמצעות עורך Drupal. לדוגמה, אפשר לערוך את פועל ה-HTTP ואת התיאור של ה-API, או מוסיפים ל-API שאילתה חדשה או פרמטר חדש של כותרת. שלך אפשרות לערוך צמתים שנוצרו מקובץ WADL או ממפרט OpenAPI, או צמתים שנוצרו במצב ה-GRU

אפשר גם לערוך את קובץ ה-WADL המקורי או את מפרט OpenAPI. בסיום עריכה, יבוא קובץ WADL או OpenAPI Specification חזרה למודל כגרסה חדשה, לאחר מכן מעבדים ומפרסמים את השינויים כפי שמתואר למעלה.

כדי לערוך צומת באמצעות עורך Drupal:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. מדפדפים לצומת Drupal שתואם למסמכי התיעוד של ה-API. עריכה.
  3. כדי להשתמש בעורך של Drupal, בוחרים באפשרות עריכה.
  4. בסיום העריכה, בוחרים באפשרות שיטת עדכון.

לחלופין, אפשר לערוך את הצומת דרך מודל SmartDocs:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. בוחרים באפשרות תוכן > SmartDocs ב- תפריט הניהול של Drupal.
  3. למודל שרוצים לעדכן, בוחרים באפשרות API Revisions בקטע תפעול.
  4. בוחרים את הגרסה הקודמת של המודל שרוצים לפרסם.
  5. בוחרים באפשרות Edit method מתוך התפריט הנפתח Operations עבור שאותה רוצים לערוך.

כדי למחוק צומת:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. בוחרים באפשרות תוכן > SmartDocs ב- תפריט הניהול של Drupal.
  3. למודל שרוצים לעדכן, בוחרים באפשרות API Revisions בקטע תפעול.
  4. בוחרים את הגרסה הקודמת של המודל שרוצים לפרסם.
  5. בוחרים באפשרות מחיקת שיטה ב: בתפריט הנפתח Operations של ה-method.
    זהירות: מחיקת הצומת מסירה את ה-API גם מהמודל. אם שרוצים לבטל את הפרסום של ה-API כך שיהיה מוסתר מהמשתמשים בפורטל, אבל לא רוצה למחוק אותו. עליכם לבטל את הפרסום של הצומת כפי שמתואר למעלה.

הפורטל כולל דוח מובנה שמציג מידע על כל צומת שעבר רינדור על ידי מודל SmartDocs שכבר לא מתייחס לשיטות תקפות של המודל. אפשר להיכנס לדוח לפי בוחרים באפשרות Reports (דוחות) בתפריט Drupal ואז בוחרים את הדוח שנקרא סטטוס הצומת של SmartDocs.

ייצוא וייבוא של מודל

SmartDocs מאפשר לייצא מודל קיים לקובץ. לדוגמה, אפשר להגדיר בסביבת ייצור ובסביבת Staging. לאחר מכן מבצעים את כל העריכות ב-SmartDocs בתהליך הסביבה. כשתהיו מוכנים לפרסם את ממשקי ה-API שלכם, תוכלו לייצא את מודל ה-Staging ולייבא אותו. לתוך מודל הייצור.

ייבוא מודל יוצר גרסה חדשה של המודל. SmartDocs מנסה להתאים קיים ממשקי API במודל עם ממשקי API מיובאים. אם מערכת SmartDocs מזהה התאמה, הייבוא יעדכן את Drupal שתואם ל-API הקיים. אם מערכת SmartDocs לא מזהה התאמה, הייבוא יוצרת צומת Drupal חדש עבור ה-API.

לדוגמה, יש לכם POST API שתואם לצומת Drupal עם המזהה 91. לאחר מכן לייבא מודל, ו-SmartDocs מזהה התאמה של POST API במודל המיובא POST API. אם מבצעים עדכונים ב-POST API, מעדכנים את צומת Drupal 91. אם SmartDocs לא מזהה התאמה, היא יוצרת צומת Drupal חדש עם מזהה חדש.

Drupal מבצע את ההתאמה באמצעות המאפיינים הבאים של ה-API:

  • internalName: שם המודל הפנימי.
  • httpMethod: שיטת ה-HTTP של ה-API, למשל: GET, PUT, POST או מחיקה.
  • resourcePath: נתיב המשאב.
  • query params (פרמטרים של שאילתות): הפרמטרים של השאילתה שבהם משתמש ה-API.

אם כל ארבעת המאפיינים של API מיובא תואמים ל-API קיים במודל: SmartDocs מעדכנת את צומת Drupal הקיים.

המודל המיוצא מיוצג על ידי אובייקט JSON יחיד עם רשומות למשאבים שיטות. פירוש הדבר הוא שאתם יכולים לערוך את המודל המיוצא כדי לשנות משאב או שיטה, ולאחר מכן לייבא מחדש את המודל. אם עורכים את אובייקט ה-JSON, אין לשנות את השדות הבאים:

  • revisionNumber
  • createdTime
  • modifiedTime
  • apiRevisionId
  • resourceId

כדי לייצא מודל:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. יש לבחור באחת מהאפשרויות הבאות תוכן > ב-SmartDocs ב- תפריט הניהול של Drupal.
  3. לצד המודל שרוצים לייצא, בוחרים באפשרות ייצוא בקטע פעולות.
  4. בוחרים את סוג הקובץ לייצוא בתור SmartDocs JSON.
  5. לוחצים על ייצוא.
  6. תוצג בקשה לשמור את הקובץ בדיסק או לפתוח אותו בכלי עריכה.

כדי לייבא מודל:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. יש לבחור באחת מהאפשרויות הבאות תוכן > ב-SmartDocs ב- תפריט הניהול של Drupal.
  3. לצד המודל שרוצים לייבא, בוחרים באפשרות ייבוא בקטע פעולות.
  4. בוחרים באפשרות SmartDocs JSON בתפריט הנפתח בחירת פורמט.
  5. בוחרים באפשרות קובץ או כתובת URL ב- סוג ההעלאה :
    1. אם בוחרים באפשרות קובץ, מחפשים את קובץ ה-JSON.
    2. אם בוחרים באפשרות כתובת URL, צריך לציין את כתובת ה-URL של קובץ SmartDocs JSON.
  6. לוחצים על ייבוא כדי לייבא אותו למודל.
  7. תועברו לדף הפרטים של המודל, שבו תוכלו לעבד את מודל טרנספורמר. שימו לב שהייבוא יוצר גרסה חדשה של המודל.
  8. עיבוד ופרסום הצמתים.

עריכת תבנית SmartDocs

תבנית SmartDocs מגדירה איך יופיעו צמתים של Drupal במסך. כל SmartDocs יכול להשתמש באותה תבנית ברירת מחדל או שאפשר להתאים אישית באופן ידני את התבנית שבה נעשה שימוש מודל אחד.

תבנית SmartDocs כוללת קובץ תבנית המקודד כקובץ .hbr של Handlebars, קובצי CSS, וקובצי JavaScript. עם ידיות, רוב התוכן מבוסס על משתנים ביטויים של סרגלי כינויים, כמו &123;&123;body}}. רשימה של הביטויים של הכינויים מוצגים בתגובה בחלק העליון של הקובץ. מידע על להשתמש בכידון כדי להתאים אישית את התבניות בכתובת http://handlebarsjs.com.

בקטעים הבאים מוסבר איך להעלות קובץ תבנית SmartDocs מותאם אישית לשימוש כל המשתמשים מודלים חדשים או כאשר תייבא ממשקי API חדשים למודל קיים, כיצד לשחזר את קובץ ברירת המחדל המקורי של תבנית SmartDocs, ואיך לשנות את תבנית SmartDocs עבור מודל אחד.

העלאת קישור מותאם אישית קובץ תבנית של SmartDocs

אפשר להעלות קובץ תבנית SmartDocs מותאם אישית, כקובץ .hbr של Handlebars, ולהשתמש בו תבנית ברירת מחדל בעת יצירת מודלים חדשים או ייבוא ממשקי API חדשים למודל קיים.

כדי להתחיל בתהליך היצירה, צריך להשתמש בקובץ ברירת המחדל של תבנית SmartDocs של תבנית SmartDocs מותאמת אישית, ניתן להוריד עותק מ: profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr

כדי להעלות קובץ תבנית SmartDocs מותאם אישית:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. בוחרים באפשרות הגדרות אישיות > SmartDocs ב-Drupal תפריט ניהול.
  3. מרחיבים את האזור הגדרות מתקדמות בדף.
  4. בקטע 'העלאת תבנית מותאמת אישית', לוחצים על בחירת קובץ. עוברים אל קובץ .hbr של הכינויים.
  5. לוחצים על העלאה.
  6. לוחצים על Save configuration (שמירת ההגדרות האישיות).

שחזור של קובץ ברירת המחדל של תבנית SmartDocs

אפשר לשחזר את קובץ ברירת המחדל של תבנית SmartDocs. לאחר השחזור, ברירת המחדל של SmartDocs המערכת תשתמש בקובץ התבנית הזה במהלך יצירת מודלים חדשים או ייבוא ממשקי API חדשים מודל טרנספורמר.

כדי לשחזר את קובץ ברירת המחדל של תבנית SmartDocs:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. בוחרים באפשרות הגדרות אישיות > SmartDocs ב-Drupal תפריט ניהול.
  3. מרחיבים את האזור הגדרות מתקדמות בדף.
  4. בקטע 'העלאה של תבנית שיטה מותאמת אישית', לוחצים על הסרה לצד קובץ תבנית SmartDocs מותאם אישית.
  5. לוחצים על Save configuration (שמירת ההגדרות האישיות).

מתבצע שינוי תבנית SmartDocs למודל ספציפי

אפשר לשנות את התבנית שבה נעשה שימוש במודל ספציפי.

כדי לשנות את התבנית של מודל נפרד:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. יש לבחור באחת מהאפשרויות הבאות תוכן > SmartDocs ב- תפריט הניהול של Drupal.
  3. בשביל המודל שרוצים לערוך, בוחרים באפשרות הגדרות בקטע פעולות.
  4. באזור 'תבנית שיטה', עורכים את התבנית לפי הצורך.
  5. לוחצים על שמירת תבנית.
  6. דפדוף לצומת של Drupal. השינויים בתבניות אמורים להופיע בדף.

הגדרת סוג אימות של SmartDocs

ממשקי API שמוגדרים ב-SmartDocs יכולים להיות פתוחים, כלומר לא מוגדרים פרטי כניסה לאימות שנדרש כדי לגשת אליהן, או לאבטח. כדי להשתמש ב-API מאובטח, צריך להעביר פרטי כניסה כשמבצעים קריאה ל-API.

כדי להשתמש בממשק API מאובטח, SmartDocs תומך בסוגי האימות הבאים:

  • אימות בסיסי – העברת פרטי כניסה של אימות בסיסי בתור זוג של שם משתמש וסיסמה. אם לא מציינים שימוש ב-OAuth כסוג פרטי הכניסה, API ברירת המחדל היא שימוש באימות בסיסי.
  • OAuth 2.0 – ספק שירות של צד שלישי מאמת את פרטי המשתמש של המשתמש פרטי כניסה, מבטיח שלמשתמש יש הרשאה ל-API, ואז מנפיק גישה ב-Assistant. כששולחים בקשת SmartDocs לממשק API מוגן, SmartDocs בונה את הבקשה שולח אותו לספק השירות. לאחר מכן ספק השירות מאמת את האסימון ומוודא שהוא עדיין בתוקף.
  • אסימון מותאם אישית – העברת ערך אסימון ככותרת או כפרמטר של שאילתה לכל אחד מהם בקשה.

לכל סוג אימות צריך ליצור סכמת אבטחה שמגדירה המאפיינים של האימות. לדוגמה, עבור אימות אסימון מותאם אישית, סכמת אבטחה מגדירה את אופן ההעברה של האסימון (כותרת, פרמטר שאילתה, פרמטר גוף) והשם של את האסימון.

סכמת אבטחה משויכת לגרסה ספציפית של מודל. לכן, אם גרסה חדשה של מודל, תצטרכו להגדיר מחדש את תוכניות האבטחה של אותה גרסה

בקובץ WADL, ניתן לציין אם API דורש אימות באמצעות תג Apigee &lt;apigee:authentication&gt;, כפי מוצגת למטה:

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

אם ה-API פתוח, מגדירים את המאפיין required (חובה) כ-false.

שימו לב שאי אפשר לציין את סוג האימות בקובץ ה-WADL. עושים זאת כך שעורכים את הצומת ב-Drupal. מידע נוסף על קובצי WADL זמין כאן: WADL הפניה.

בדף ה-API ב-Drupal, SmartDocs מוסיף את הלחצן הבא כדי לאפשר למשתמשים לציין פרטי כניסה לאימות בסיסי:

אם תערכו את הצומת כדי להגדיר את סוג האימות ל-OAuth, SmartDocs יוסיף את הלחצן הבא לדף:

בשביל אסימון מותאם אישית, SmartDocs מוסיף:

מתבצעת הגדרה אימות בסיסי

אם משתמשים באימות בסיסי עם ה-API, צריך לציין רק את התג &lt;apigee:authentication&gt; ב-WADL שבו אתם משתמשים כדי ליצור את המודל.

כדי להחיל אימות בסיסי על שיטות שנוצרו ממקור שאינו קובץ WADL:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. בוחרים באפשרות תוכן > SmartDocs ב- תפריט הניהול של Drupal.
  3. למודל הרצוי, בוחרים באפשרות API Revisions בקטע תפעול.
  4. עבור גרסת המודל שרוצים לערוך, בוחרים באפשרות אבטחה הגדרות בקטע פעולות.
  5. בוחרים באפשרות Add Security Scheme (הוספת סכמת אבטחה).
  6. מציינים את השם של סכמת האבטחה.
  7. בוחרים באפשרות בסיסי בתור סוג.
  8. בוחרים באפשרות שליחה.
  9. לכל method במודל, עורכים את ה-method להגדרה של סכימת האבטחה שלה לסכימה הבסיסית שלכם.
    1. בוחרים באפשרות תוכן > SmartDocs ב- תפריט הניהול של Drupal.
    2. למודל הרצוי, בוחרים באפשרות API Revisions בקטע תפעול.
    3. עבור גרסת המודל שרוצים לערוך, בוחרים באפשרות גרסה פרטים בקטע פעולות.
    4. בוחרים באפשרות Edit Method (עריכת השיטה) עבור ה-API שרוצים לערוך.
    5. בוחרים את סכמת האבטחה בשביל ה-API.
    6. שומרים את ה-API.

מתבצעת הגדרה אימות OAuth 2.0

אפשר להגדיר מודל לשימוש ב-OAuth 2.0 ב-SmartDocs, במקום בברירת המחדל של אימות. פרוטוקול OAuth מוגדר בשני מיקומים:

  1. יוצרים סכימת אבטחה לכל גרסה של מודל בקטע אבטחה הגדרות של הגרסה הקודמת.
  2. לציין את מזהה הלקוח ואת סוד הלקוח לכל הגרסאות הקודמות של המודל, הגדרות של המודל.

כדי להפעיל את OAuth:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. בוחרים באפשרות תוכן > SmartDocs ב- תפריט הניהול של Drupal.
  3. למודל הרצוי, בוחרים באפשרות API Revisions בקטע 'פעולות'.
  4. בגרסת המודל שרוצים לערוך, בוחרים באפשרות הגדרות אבטחה בקטע פעולות.
  5. בוחרים באפשרות Add Security Scheme (הוספת סכמת אבטחה).
  6. מציינים את השם של סכמת האבטחה.
  7. בוחרים באפשרות OAuth 2.0 בתור סוג.
  8. מגדירים את סוג המענק.
  9. מזינים את הערכים בשדות Authorization URL ההרשאה כתובת ה-URL משמשת לקבלת אסימון הגישה.
  10. מגדירים את Authorization Verb בתור GET או POST.
  11. מזינים את כתובת ה-URL של אסימון הגישה. כתובת ה-URL של אסימון הגישה היא כתובת ה-URL שמשמשת להחליף את אסימון הבקשה באסימון גישה.
  12. מזינים את שם הפרמטר של אסימון הגישה.
  13. משתמשים בתו In כדי לציין איך להעביר את האסימון: כותרת, Query או Body.
  14. מגדירים את היקפי ההרשאות של OAuth.
  15. בוחרים באפשרות שליחה.
  16. בוחרים באפשרות תוכן > SmartDocs ב- תפריט הניהול של Drupal.
  17. עבור המודל, בוחרים באפשרות הגדרות בקטע פעולות
  18. מזינים את הערכים ב-Client ID וב-Client סודי.
  19. בוחרים באפשרות שמירת הגדרות האימות באמצעות תבניות.
  20. לכל method במודל, עורכים את ה-method להגדרה של סכימת האבטחה שלה לסכימת האבטחה של OAuth.
    1. בוחרים באפשרות תוכן > SmartDocs ב- תפריט הניהול של Drupal.
    2. למודל הרצוי, בוחרים באפשרות API Revisions בקטע תפעול.
    3. עבור גרסת המודל שרוצים לערוך, בוחרים באפשרות גרסה פרטים בקטע פעולות.
    4. בוחרים באפשרות Edit Method (עריכת השיטה) עבור ה-API שרוצים לערוך.
    5. בוחרים את סכמת האבטחה בשביל ה-API.
    6. שומרים את ה-API.

הגדרת אימות של אסימון מותאם אישית

אפשר להגדיר מודל לשימוש באימות עם אסימון בהתאמה אישית.

כדי להפעיל אסימונים מותאמים אישית:

  1. מתחברים לפורטל כמשתמשים עם הרשאות אדמין או הרשאות ליצירת תוכן.
  2. בוחרים באפשרות תוכן > SmartDocs ב- תפריט הניהול של Drupal.
  3. למודל הרצוי, בוחרים באפשרות API Revisions בקטע תפעול.
  4. עבור גרסת המודל שרוצים לערוך, בוחרים באפשרות אבטחה הגדרות בקטע פעולות.
  5. בוחרים באפשרות Add Security Scheme (הוספת סכמת אבטחה).
  6. מציינים את השם של סכמת האבטחה.
  7. בוחרים באפשרות Apikey בתור Type.
  8. מגדירים את שם Param שמכיל את האסימון.
  9. משתמשים בפונקציה In כדי לציין איך להעביר את האסימון: כותרת, שאילתה, או גוף.
  10. בוחרים באפשרות שליחה.
  11. לכל method במודל, עורכים את ה-method להגדרה של סכימת האבטחה שלה לסכימת האסימונים.
    1. בוחרים באפשרות תוכן > SmartDocs ב- תפריט הניהול של Drupal.
    2. למודל הרצוי, בוחרים באפשרות API Revisions בקטע תפעול.
    3. עבור גרסת המודל שרוצים לערוך, בוחרים באפשרות גרסה פרטים בקטע פעולות.
    4. בוחרים באפשרות Edit Method (עריכת השיטה) עבור ה-API שרוצים לערוך.
    5. בוחרים את סכמת האבטחה בשביל ה-API.
    6. שומרים את ה-API.

מחיקת מודל

כשמוחקים מודל (תוכן > SmartDocs, מחיקה ב: שדה הפעולות ב-Drupal), המודל נמחק מהארגון ב-Edge. כלומר, אם פורטלים אחרים מפנים למודל, המודל כבר לא זמין. לקבלת מידע נוסף, מידע על מודלים ותבניות של SmartDoc