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

Swagger תומך גם במטעני JSON וגם ב-XML. התיעוד שהוא מייצר מתאים למפתחים וללא מפתחים לשימוש.

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

שלב 1: יצירת ה-API

לפני שתתחיל, עליך ליצור ממשק API להדגמה ש-Swagger יפיק את התיעוד שלו.

אתה תיצור את API ההדגמה מאפס באמצעות NestJS CLI.

ראשית, צור פרויקט NestJS חדש על ידי הפעלת:

קן חדש <שם הפרויקט שלך>

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

CD <שם הפרויקט שלך>

לאחר מכן, תיצור REST API עם ה-CLI על ידי הפעלת:

הדגמת משאבים ליצירת קן --ללא מפרט

תראה שאילתה ששואלת: "באיזו שכבת תחבורה אתה משתמש?" בחר REST API.

תראה שאילתה נוספת ששואלת: "האם תרצה ליצור נקודות כניסה CRUD?" סוּג י ופגע להיכנס.

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

שלב 2: התקן את Swagger

instagram viewer

התקן את Swagger ואת ספריית ממשק המשתמש האקספרס שלו על ידי הפעלת:

npm להתקין--שמור @nestjs/swagger swagger-ui-express

שלב 3: הגדר את Swagger

אצלך main.ts קובץ, ייבוא SwaggerModule ו DocumentBuilder מ @nestjs/swagger.

DocumentBuilder מסייע בבניית מסמך בסיס. הוא מספק מספר שיטות שאתה יכול לשרשר יחד ולסגור עם לִבנוֹת שיטה.

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

ליצור תצורה משתנה אובייקט שלך אתחול מתפקד כך:

const config = חָדָשׁ DocumentBuilder()
 .setTitle('Demo API')
 .setDescription('A Demo API עם פונקציונליות CRUD')
 .setVersion('1.0')
 .לִבנוֹת();

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

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

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

constמסמך = SwaggerModule.createDocument (אפליקציה, config);

לאחר מכן, התקשר ל- להכין שיטה על SwaggerModule. שיטת ההגדרה לוקחת שלושה ארגומנטים:

  1. נתיב ממשק המשתמש של Swagger. לפי מוסכמה, אתה יכול להשתמש ב- "API".
  2. מופע אפליקציה
  3. המסמך המלא

בנוסף, שיטת ההגדרה לוקחת אובייקט אפשרויות אופציונלי. לִרְאוֹת התיעוד של NestJS על אפשרויות מסמך Swagger כדי ללמוד עוד על זה.

ככה:

SwaggerModule.setup('API', אפליקציה, מסמך);

התחל את היישום שלך ועבור אל http://localhost:/api

אתה אמור לראות את ממשק המשתמש של Swagger מוצג בדף.

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

שלב 4: התאמה אישית של מאפייני API

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

ככה:

// demo.controller.ts
יְבוּא { ApiTags } מ '@nestjs/swagger';
@ApiTags('הַדגָמָה')
@בקר('הַדגָמָה')
יְצוּאמעמד DemoController {

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

כדי להצהיר על המאפיינים שלהם בממשק המשתמש, פשוט הוסף מעצבים. סמן כל מאפיין נדרש ב- @ApiProperty מְעַצֵב. הוספת הערות למאפיינים אופציונליים באמצעות ה- @ApiPropertyOptional מְעַצֵב.

לדוגמה:

// create-demo.dto.ts
יְבוּא { ApiProperty, ApiPropertyOptional } מ '@nestjs/swagger';
יְצוּאמעמד CreateDemoDto {
@ApiProperty({
סוּג: חוּט,
 תיאור: 'זהו נכס נדרש',
 })
 תכונה: חוּט;
@ApiPropertyOptional({
סוּג: חוּט,
 תיאור: 'זהו נכס אופציונלי',
 })
 אופציונלי מאפיין: חוּט;
}

מעצבי @ApiProperty ו-@ApiPropertyOptional מקבלים כל אחד אובייקט אופציות. אובייקט זה מתאר את המאפיין הבא להלן.

שימו לב שאובייקט האפשרויות משתמש ב-JavaScript, לא ב-TypeScript. מכאן ההצהרות מסוג JavaScript (כלומר מחרוזת, לא מחרוזת).

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

שלב 5: הגדר תגובות API

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

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

מעצבי @ApiResponse מקבלים אובייקט אופציונלי שמתאר את התגובה.

תגובות POST נפוצות

עבור בקשת POST, התגובות הסבירות כוללות:

  • ApiCreatedResponse, עבור 201 תגובות מוצלחות שנוצרו.
  • ApiUnprocessableEnityResponse, עבור 422 תגובות ישות בלתי ניתנות לעיבוד שנכשלו.
  • ApiForbiddenResponse, עבור 403 תגובות אסורות.

לדוגמה:

// demo.controller.ts
@הודעה()
@ApiCreatedResponse({ description: 'נוצר בהצלחה' })
@ApiUnprocessableEntityResponse({ description: 'Bad Request' })
@ApiForbiddenResponse({ description: 'בקשה לא מורשית' })
 לִיצוֹר(@גוּף() createDemoDto: CreateDemoDto) {
לַחֲזוֹרזֶה.demoService.create (createDemoDto);
 }

תגובות GET נפוצות

עבור בקשות GET, התגובות הסבירות כוללות:

  • ApiOkResponse, עבור 200 תגובות בסדר.
  • ApiForbiddenResponse, עבור 403 תגובות אסורות.
  • ApiNotFoundResponse, עבור 404 תגובות שלא נמצאו.

לדוגמה:

// demo.controller.ts
@לקבל()
@ApiOkResponse({ description: 'המשאבים הוחזרו בהצלחה' })
@ApiForbiddenResponse({ description: 'בקשה לא מורשית' })
 מצא הכל() {
לַחֲזוֹרזֶה.demoService.findAll();
 }
@לקבל(':תְעוּדַת זֶהוּת')
@ApiOkResponse({ description: 'המשאב הוחזר בהצלחה' })
@ApiForbiddenResponse({ description: 'בקשה לא מורשית' })
@ApiNotFoundResponse({ description: 'משאב לא נמצא' })
 findOne(@פארם('אני עשיתי: חוּט) {
לַחֲזוֹרזֶה.demoService.findOne(+id);
 }

תגובות PATCH ו-UPDATE נפוצות

עבור בקשות PATCH ו-UPDATE, התגובות הסבירות כוללות:

  • ApiOkResponse, עבור 200 תגובות בסדר.
  • ApiNotFoundResponse, עבור 404 תגובות שלא נמצאו.
  • ApiUnprocessibleEntityResponse, עבור 422 תגובות ישות בלתי ניתנות לעיבוד שנכשלו.
  • ApiForbiddenResponse, עבור 403 תגובות אסורות.

לדוגמה:

// demo.controller.ts
@תיקון(':תְעוּדַת זֶהוּת')
@ApiOkResponse({ description: 'המשאב עודכן בהצלחה' })
@ApiNotFoundResponse({ description: 'משאב לא נמצא' })
@ApiForbiddenResponse({ description: 'בקשה לא מורשית' })
@ApiUnprocessableEntityResponse({ description: 'Bad Request' })
 עדכון(@פארם('אני עשיתי: חוּט, @גוּף() updateDemoDto: UpdateDemoDto) {
לַחֲזוֹרזֶה.demoService.update(+id, updateDemoDto);
 }

תגובות מחק נפוצות

עבור בקשות מחיקה, התגובות הסבירות כוללות:

  • ApiOkResponse, עבור 200 תגובות בסדר.
  • ApiForbiddenResponse, עבור 403 תגובות אסורות.
  • ApiNotFoundResponse, עבור 404 תגובות שלא נמצאו.

לדוגמה:

// demo.controller.ts
@לִמְחוֹק(':תְעוּדַת זֶהוּת')
@ApiOkResponse({ description: 'המשאב הוחזר בהצלחה' })
@ApiForbiddenResponse({ description: 'בקשה לא מורשית' })
@ApiNotFoundResponse({ description: 'משאב לא נמצא' })
 לְהַסִיר(@פארם('אני עשיתי: חוּט) {
לַחֲזוֹרזֶה.demoService.remove(+id);
 }

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

צפייה בתיעוד שלך

לאחר השלמת ההגדרה, תוכל להציג את התיעוד שלך ב- מארח מקומי:/api. זה אמור להעלות את תיעוד ה-API האינטראקטיבי שלך.

היסודות של תיעוד Swagger API הם התיאור, סוגי התגובות והגדרת הסכימה. אלו הם הדברים הבסיסיים הדרושים ליצירת תיעוד API טוב.