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

يدعم Swagger حمولات JSON و XML. الوثائق التي يتم إنشاؤها مناسبة لاستخدامها للمطورين وغير المطورين.

يمكنك توثيق واجهات برمجة تطبيقات الويب الخاصة بك في NestJS عبر Swagger باستخدام أدوات تزيين بسيطة ، دون الحاجة إلى مغادرة IDE الخاص بك.

الخطوة 1: إنشاء API

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

ستقوم بإنشاء واجهة برمجة التطبيقات التجريبية من البداية باستخدام NestJS CLI.

أولاً ، قم بإنشاء مشروع NestJS جديد من خلال تشغيل:

عش جديد <اسم مشروعك>

بعد ذلك ، قم بتغيير الدليل إلى مشروعك الذي تم إنشاؤه بالفعل عن طريق تشغيل:

قرص مضغوط <اسم مشروعك>

بعد ذلك ، ستنشئ واجهة برمجة تطبيقات REST باستخدام CLI عن طريق تشغيل:

عش توليد العرض التوضيحي للموارد --لا المواصفات

سترى استعلامًا يسألك ، "ما طبقة النقل التي تستخدمها؟" تحديد REST API.

سترى استعلامًا آخر يسأل ، "هل ترغب في إنشاء نقاط دخول CRUD؟" يكتب ص وضرب يدخل.

instagram viewer

الأمر أعلاه يولد واجهة برمجة تطبيقات REST تعمل بكامل طاقتها مع نقاط نهاية CRUD وبدون ملفات اختبار الوحدة. ومن ثم ، فإن --لا المواصفات علم في الأمر أعلاه.

الخطوة الثانية: تثبيت Swagger

قم بتثبيت Swagger ومكتبة Express UI الخاصة به عن طريق تشغيل:

npm تثبيت- حفظ @ nestjs / swagger swagger-ui-express

الخطوة 3: تكوين Swagger

في الخاص بك main.ts ملف استيراد SwaggerModule و DocumentBuilder من @ nestjs / اختيال.

يساعد DocumentBuilder في هيكلة المستند الأساسي. يوفر العديد من الطرق التي يمكنك ربطها ببعضها البعض وإغلاقها بامتداد يبني طريقة.

تتيح هذه الطرق تكوين العديد من السمات ، مثل العنوان والوصف والإصدار.

إنشاء التكوين متغير الكائن في الخاص بك التمهيد تعمل كالتالي:

مقدار ثابت التكوين = الجديد منشئ المستندات ()
 .setTitle ('Demo API')
 .setDescription ('واجهة برمجة تطبيقات تجريبية مع وظيفة CRUD ')
 .setVersion ('1.0')
 .يبني()؛

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

بعد ذلك ، ستحتاج إلى إنشاء مستند كامل بكل مسارات HTTP المحددة باستخدام المستند الأساسي.

للقيام بذلك ، اتصل ب إنشاء مستند الطريقة على SwaggerModule. يقبل createDocument وسيطتين: مثيل التطبيق وكائن خيارات Swagger. قم بتخزين نتيجة هذا الاستدعاء في متغير لاستخدامه لاحقًا:

مقدار ثابتوثيقة = SwaggerModule.createDocument (التطبيق ، التكوين) ؛

بعد ذلك ، اتصل بـ اقامة الطريقة على SwaggerModule. تأخذ طريقة الإعداد ثلاث وسيطات:

  1. مسار Swagger UI. حسب الاصطلاح ، يمكنك استخدام "api".
  2. مثيل تطبيق
  3. الوثيقة كاملة

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

مثل ذلك:

SwaggerModule.setup ('api'، التطبيق ، المستند) ؛

ابدأ طلبك وانتقل إلى http://localhost:/api

يجب أن تشاهد Swagger UI معروضة على الصفحة.

الصورة أعلاه هي العرض الافتراضي لواجهة Swagger UI ، مع تحديد جميع مسارات HTTP في وحدة التحكم الخاصة بك. ستحتاج إلى تخصيصه ليلائم وظائف واجهة برمجة التطبيقات لديك.

الخطوة 4: تخصيص خصائص API

بشكل افتراضي ، يسبق Swagger قسم مسار HTTP بأكمله بعنوان يقرأ "افتراضي". يمكنك تغيير هذا عن طريق إضافة تعليق توضيحي لفئة وحدة التحكم الخاصة بك بامتداد تضمين التغريدة المصمم وتمرير العلامة المفضلة لديك كحجة.

مثل ذلك:

// demo.controller.ts
يستورد {ApiTags} من 'تضمين التغريدة/swagger';
تضمين التغريدة("عرض توضيحي")
@مراقب("تجريبي")
يصدّرصف دراسي DemoController {

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

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

فمثلا:

// create-demo.dto.ts
يستورد {ApiProperty ، ApiPropertyOptional} من 'تضمين التغريدة/swagger';
يصدّرصف دراسي CreateDemoDto {
تضمين التغريدة({
يكتب: سلسلة,
 الوصف: "هذه خاصية مطلوبة" ،
 })
 منشأه: سلسلة;
تضمين التغريدة({
يكتب: سلسلة,
 الوصف: "هذه خاصية اختيارية" ،
 })
 اختياري سلسلة;
}

يقبل كل من مصممي الديكورApiProperty وApiPropertyOptional كائن خيارات. يصف هذا الكائن الخاصية التالية.

لاحظ أن كائن الخيارات يستخدم JavaScript وليس TypeScript. ومن هنا جاءت تعريفات نوع جافا سكريبت (أي سلسلة ، وليس سلسلة).

يضيف التعليق التوضيحي لخصائص كائن نقل البيانات مثالاً على البيانات المتوقعة إلى قسم المخططات. يقوم أيضًا بتحديث مسار HTTP المرتبط بمثال للبيانات المتوقعة.

الخطوة 5: تعيين استجابات API

في فئة وحدة التحكم الخاصة بك ، استخدم ملف تضمين التغريدة لتوثيق جميع الاستجابات المحتملة لكل مسار HTTP. لكل نقطة نهاية ، يصف مصممي الديكورApiResponse نوع الاستجابات المتوقعة.

لقد أوضحنا استجابات HTTP الشائعة، في حال لم تكن معتادًا على ما تعنيه.

يقبل مصممي الديكورApiResponse كائنًا اختياريًا يصف الاستجابة.

ردود POST الشائعة

بالنسبة لطلب POST ، تشمل الردود المحتملة ما يلي:

  • ApiCreatedResponse، للحصول على 201 استجابات تم إنشاؤها بنجاح.
  • ApiUnprocessableEnityResponse، لـ 422 استجابات كيانات غير قابلة للمعالجة فاشلة.
  • ApiForbiddenResponse، لـ 403 ردود ممنوعة.

فمثلا:

// demo.controller.ts
@بريد()
تضمين التغريدة({description: "Created Succesfully"})
تضمين التغريدة({وصف: "طلب سيء"})
تضمين التغريدة({وصف: "طلب غير مصرح به"})
 خلق(@الجسم() createDemoDto: CreateDemoDto) {
إرجاعهذه.demoService.create (createDemoDto) ،
 }

ردود GET المشتركة

بالنسبة لطلبات GET ، تشمل الردود المحتملة ما يلي:

  • ApiOkResponse، لـ 200 إجابة جيدة.
  • ApiForbiddenResponse، لـ 403 ردود ممنوعة.
  • ApiNotFoundResponse، لـ 404 استجابات غير موجودة.

فمثلا:

// demo.controller.ts
@احصل على()
تضمين التغريدة({وصف: "تم إرجاع الموارد بنجاح"})
تضمين التغريدة({وصف: "طلب غير مصرح به"})
 جد كل() {
إرجاعهذه.demoService.findAll () ،
 }
@احصل على(':هوية شخصية')
تضمين التغريدة({وصف: "تم إرجاع المورد بنجاح"})
تضمين التغريدة({وصف: "طلب غير مصرح به"})
تضمين التغريدة({وصف: "المورد غير موجود"})
 findOne (تضمين التغريدة('فعلتُ: سلسلة) {
إرجاعهذه.demoService.findOne (+ id) ،
 }

ردود التصحيح والتحديث المشتركة

بالنسبة لطلبات التصحيح والتحديث ، تتضمن الردود المحتملة ما يلي:

  • ApiOkResponse، لـ 200 إجابة جيدة.
  • ApiNotFoundResponse، لـ 404 استجابات غير موجودة.
  • ApiUnprocessibleEntityResponse، لـ 422 استجابات كيانات غير قابلة للمعالجة فاشلة.
  • ApiForbiddenResponse، لـ 403 ردود ممنوعة.

فمثلا:

// demo.controller.ts
@رقعة(':هوية شخصية')
تضمين التغريدة({وصف: "تم تحديث المورد بنجاح"})
تضمين التغريدة({وصف: "المورد غير موجود"})
تضمين التغريدة({وصف: "طلب غير مصرح به"})
تضمين التغريدة({وصف: "طلب سيء"})
 تحديث(تضمين التغريدة('فعلتُ: سلسلة, @الجسم() updateDemoDto: UpdateDemoDto) {
إرجاعهذه.demoService.update (+ id، updateDemoDto) ؛
 }

استجابات الحذف الشائعة

بالنسبة لطلبات الحذف ، تشمل الردود المحتملة ما يلي:

  • ApiOkResponse، لـ 200 إجابة جيدة.
  • ApiForbiddenResponse، لـ 403 ردود ممنوعة.
  • ApiNotFoundResponse، لـ 404 استجابات غير موجودة.

فمثلا:

// demo.controller.ts
@حذف(':هوية شخصية')
تضمين التغريدة({وصف: "تم إرجاع المورد بنجاح"})
تضمين التغريدة({وصف: "طلب غير مصرح به"})
تضمين التغريدة({وصف: "المورد غير موجود"})
 إزالة(تضمين التغريدة('فعلتُ: سلسلة) {
إرجاعهذه.demoService.remove (+ id) ؛
 }

يقوم هؤلاء المصممون بتعبئة وثائقك بالردود المحتملة. يمكنك عرضها باستخدام القائمة المنسدلة بجانب كل مسار.

عرض الوثائق الخاصة بك

عند اكتمال الإعداد ، يمكنك عرض الوثائق الخاصة بك على المضيف المحلي:/api. يجب أن يعرض وثائق API التفاعلية الخاصة بك.

أساسيات وثائق Swagger API هي الوصف وأنواع الاستجابة وتعريف المخطط. هذه هي الأشياء الأساسية اللازمة لإنشاء وثائق API جيدة.