PracticU

יצירת דוקומנטציה
דף בדיקה - מנגנון Swagger

בלי כתוביותעם כתוביות
PracticU › קורס דוט-נט - NET Core. - עם Rest API › יצירת דוקומנטציה דף בדיקה - מנגנון Swagger
יצירת דוקומנטציה דף בדיקה - מנגנון Swagger
מוסיפים ל-REST API את Swagger: אתר שנבנה אוטומטית ומתעד את כל ה-routes ומאפשר לבדוק אותם בדפדפן, בדומה ל-Postman.
השלבים העיקריים
1. מה זה Swagger: חלק ממוסכמת תיעוד ל-REST API. הוא לא מחליף את Postman, שמציע הרבה יותר, אבל מתכנתים יכולים לקרוא דרכו תיעוד ולבדוק את ה-API אוטומטית. אפשר היה לסמן Enable Swagger בעת פתיחת הפרויקט.
2. התקנה: ב-Package Manager מתקינים את Swashbuckle.AspNetCore.
3. שירותים ב-Program: אחרי AddControllers מוסיפים builder.Services.AddEndpointsApiExplorer(), שחוקר את כל ה-endpoints (נקודות הקצה, כלומר ה-routes), ואת builder.Services.AddSwaggerGen().
4. הפעלה: בסוף הבנייה, לפני ההרצה, בתוך תנאי app.Environment.IsDevelopment(), מפעילים app.UseSwagger() ו-app.UseSwaggerUI().
5. הדפדפן: launch browser מוגדר מחדש ל-true, כי Swagger מוצג בדפדפן. גולשים אל /swagger ומגיעים לדף index.html שהמערכת בנתה לפי הקונטרולרים.
6. שימוש בדף: לכל route מוצגים המתודה, הפרמטרים והתשובות. ב-Try it out לוחצים Execute ורואים את הבקשה כפקודת curl, את ה-route, את ה-response ואת ה-response headers.
7. דוגמאות: GET לספר לפי ID 1 ו-2. POST של ספר CSS בלי ID, שמחזיר ID 5 ונשמר במסד. קריאה עם minPrice ו-maxPrice בין 50 ל-70.
8. הרצה אוטומטית: אפשר להגדיר שהמערכת תפתח את Swagger בכל Ctrl+F5.
פקודות והגדרות
- Install-Package Swashbuckle.AspNetCore
- AddEndpointsApiExplorer, AddSwaggerGen
- UseSwagger, UseSwaggerUI רק בסביבת פיתוח
בסיום המודול יש REST API מחולק לשכבות, ובהמשך הקורס מטפלים בשגיאות, בתמונות, באותנטיקציה וב-middleware.
מילון מושגים:
REST – סגנון לבניית ממשקי API מעל HTTP, המבוסס על משאבים ועל שיטות סטנדרטיות כמו GET ו-POST.
Postman – כלי לבדיקת API: שליחת בקשות HTTP לשרת ובחינת התגובות, נפוץ בפיתוח ובבדיקות.
ראוט – הגדרה שמקשרת כתובת בקשה לקוד שמטפל בה באפליקציה; גם מסלול שדרכו עוברות חבילות ברשת.
תגובה – המידע שהשרת מחזיר ללקוח בתשובה לבקשה, הכולל בדרך כלל נתונים וקוד סטטוס.
GET – שיטת HTTP לבקשת מידע מהשרת בלי לשנות אותו; הפרמטרים מועברים בדרך כלל בכתובת.
POST – שיטת HTTP לשליחת נתונים לשרת כדי ליצור או לעדכן משאב, למשל שליחת טופס.
CSS – שפת עיצוב שקובעת את המראה של דפי אינטרנט: צבעים, גופנים, מיקום וסידור הרכיבים.
Middleware – שכבת תוכנה שמתווכת בין רכיבים ומטפלת בבקשות בדרכן, למשל לאימות, רישום לוג או עיבוד נתונים.

פרקי ההרצאה: יצירת דוקומנטציה דף בדיקה - מנגנון Swagger

  1. 00:00

    מהו Swagger ו-OpenAPI

  2. 00:57

    התקנת Swashbuckle

  3. 01:53

    רישום Swagger ב-Program

  4. 03:07

    הפעלת Swagger בסביבת Development

תמלול ההרצאה: יצירת דוקומנטציה דף בדיקה - מנגנון Swagger

הטקסט המלא של הדקות הראשונות בהרצאה «יצירת דוקומנטציה דף בדיקה - מנגנון Swagger» בקורס הווידאו של PracticU – כתוביות בעברית עם זמן התחלה לכל פסקה. כך תוכלו לקרוא ולחפש את הנושאים לפני שמתחילים ללמוד.

  1. 00:02

    אחרי שראינו את כל הראוטים השונים ואיך אנחנו יכולים להשתמש בקווירי סטרינג, בואו נבין רגע מה זה ה-enable swagger שהיה בהתחלה ושלא בחרנו אותו.

  2. 00:16

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

  3. 00:38

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

  4. 00:53

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

  5. 01:02

    כל מה שאנחנו רוצים זה להיכנס ל-Package Manager, ולבצע התקנה Install Package של איזושהי התקנה מוזרה, שנקראת Swashbuckle, בצורה כזאת, נקודה ASP.NET Core.

  6. 01:20

    בואו ניתן לו להתקין, ונראה לי שיש לי פה איזושהי בעיה. סואש, בואו נראה עוד פעם, אם טעיתי, סואש, כן, פה זה U, טעות שלי, go. והנה יש לנו פה את ההתקנה, יופי, את זה אפשר לסגור.

  7. 01:38

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

  8. 01:53

    עכשיו אנחנו צריכים לחבר כמה דברים למאין בשביל לאפשר את זה. הדבר הראשון שאנחנו רוצים לעשות, איך שבעצם יש לנו פה את ה-Services, זה אפילו נעשה את זה, האמת אחרי ה-Add Controllers, בואו נעשה את זה פה, builder.services.addEndpointAPIExplorer, זאת תקודה שבעצם מאפשרת לקרוא,

  9. 02:23

    את כל ה-endpoints שבנינו, לחקור אותם. ה-endpoints זה מילה נרדפת ל-routes השונים. route, נקודת הקצה, לאן גולשים אליה, נקראת גם endpoints. הדבר הבא שאנחנו רוצים זה builder, אופה, טעות שלי, builder.services.add, swagger, gen, כלומר, generator, to generate. יאפשר לנו...

  10. 02:52

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

  11. 03:12

    אם app.environment, הסביבה כרגע שאנחנו עובדים בה, is development, האם אנחנו בעצם נמצאים בשלב הפיתוח, אז app.useSwagger, בוא

לקורס המלא: קורס דוט-נט - NET Core. - עם Rest API

ההרצאה הקודמת: שימוש ב-QueryString - דוט נט NET Core.

ההרצאה הבאה: הבנה של Middleware - Filters

הרצאות קשורות מקורסים אחרים

  • בדיקות תעוד - דוקומנטציה
  • פוסטמן מול Swagger
  • מבוא למתודולוגיות בדיקה
  • פעילויות בדיקה מרכזיות

קורסים נוספים במסלול

  • קורס Entity Framework Core - עבודה עם מסד נתונים בדוט-נט
  • קורס ASP.NET
  • קורס MVC
  • קורס Git ו-GitHub עם Visual Studio