שימוש ב-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 כדי ליצור תיעוד אינטראקטיבי עבור ממשק ה-API לניהול Edge. תוכלו לעיין במסמכי התיעוד בנושא API כאן.

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

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

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

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

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

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

מגלים את ממשק ה-API של Hello World:

1. לוחצים על Hello World API (ממשק API של Hello World). מוצג דף הסיכום של Hello World API:
   
2. לוחצים על הצגת אישור של ה-API. מסמכי ה-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 באמצעות model, שבו המודל מכיל את כל המידע על ממשקי ה-API שלך. הפורטל מחלץ מידע על ממשקי ה-API שלך מהמודל כדי לעבד את דפי התיעוד בפורטל כצומתי Drupal, כאשר כל צומת Drupal תואם לדף תיעוד בפורטל.

כדי להשתמש ב-Smart Docs, צריך לבצע את השלבים הכלליים הבאים:

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 בפורטל.

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

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

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

התבניות שולטות במראה ובחוויה של ה-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. בוחרים באפשרות Modules (מודולים) בתפריט הניהול של Drupal.
6. בחר באפשרות SmartDocs -> Permissions (הרשאות) וודא שהאפשרות 'בצע משימות ניהול של המודול SmartDocs' עבור תפקיד 'מנהל מערכת' מופעלת.
7. בתפריט הניהול של Drupal, בוחרים באפשרות Configuration > Dev Portal.
8. מגדירים את הזמן הקצוב לתפוגה של החיבור ותם הזמן הקצוב לתפוגה של הבקשה ל-16 שניות.
9. שומרים את התצורה.
10. קובעים את ההגדרות של כתובות ה-URL:
    1. בתפריט Drupal, בוחרים באפשרות Configuration > Search and metadata > כתובות URL חלופיות > Settings (הגדרות אישיות > חיפוש ומטא-נתונים).
    2. מגדירים את אורך הכינוי המקסימלי ואת אורך הרכיב המקסימלי ל-255.
    3. מרחיבים את האפשרות פיסוק.
    4. בהגדרות של סוגר מסולסל שמאלי ({) וסוגר מסולסל ימני (}), בוחרים באפשרות אין פעולה (אין להחליף).
    5. לוחצים על Save configuration (שמירת ההגדרות האישיות).
11. אם פורטל המפתחים שלך ייחשף למשתמשים ברשת פנימית ללא גישה לאינטרנט, או אם קבוצת משנה של ממשקי ה-API נמצאת ברשת פרטית, עליך להגדיר את כתובת ה-URL של שרת ה-proxy של SmartDocs באופן הבא:
    1. בוחרים באפשרות Configuration > SmartDocs (הגדרה) בתפריט של Drupal Administration (ניהול) 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, or delete.
• resourcePath: נתיב המשאב.

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

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

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

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

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

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

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

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

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

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

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

ייבוא של WADL

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

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

ייבוא של מפרט OpenAPI

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

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

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

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

יצירה ידנית של משאבים ושיטות

אם אין לך קובץ 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. בתפריט הניהול של Drupal, בוחרים באפשרות תוכן > SmartDocs.
3. למודל שרוצים לעדכן, בוחרים באפשרות הוספת גרסה בקטע פעולות.
4. בדף הוספת גרסה של API, מזינים את המידע הבא:
   • Display Name (שם לתצוגה): השם של הגרסה הקודמת כפי שהוא מופיע בפורטל.
   • מזהה גרסה: מזהה קצר של הגרסה.
   • תיאור: תיאור של הגרסה הקודמת.
   • כתובת URL בסיסית: כתובת ה-URL הבסיסית של כל ממשקי ה-API בגרסה הקודמת של המודל. מודל יכול להשתמש בכתובות URL בסיסיות שונות לכל גרסה. לדוגמה, אתם כוללים אינדיקטור של גרסה בכתובת ה-URL הבסיסית. בגרסה הראשונה של המודל, כתובת ה-URL הבסיסית היא:
     https://myCompany.com/v1
     בגרסה הבאה, כתובת ה-URL הבסיסית יכולה להיות:
     https://myCompany.com/v2
5. בוחרים באפשרות הוספת גרסה קודמת. תתבצע הפניה מחדש לדף הגרסה של המודל. עכשיו אפשר להגדיר משאבים במודל.

הגדרת משאב

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

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

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

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

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

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

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

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

[
 {
  "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 בכתובת ה-URL כדי לשלוח בקשה.

הגדרת שיטה

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

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

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

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

כדי להגדיר שיטה:

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

עיבוד של מודל

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

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

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

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

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

פרסום צמתים

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

עריכת צומת

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

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

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

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

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

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

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