هل سبق لك أن أردت الحصول على وثائق اختيارية لواجهة برمجة التطبيقات السريعة الخاصة بك بناءً على التعليقات التوضيحية؟ لدي. ولسوء الحظ لم تجد أي طريقة للقيام بذلك دون الحاجة إلى إنشاء ملف swagger.json يدويًا. كانت رغبتي بسيطة كما يلي: أريد أن يكون لدي تطبيق صريح ونظيف مع نقاط نهاية متعددة وأريد الاحتفاظ بمستندات التبادل لكل نقطة نهاية قريبة من تطبيق نقطة النهاية ، وليس في ملف منفصل.

ربما أفتقر إلى بعض مهارات google ، لكنني قررت أنه سيكون من الأسهل بالنسبة لي إنشاء مثل هذه الأداة. ومن هنا: mgr-swagger-express

الابتداء

سيتم كتابة المثال هنا في TypeScript ، ولكن يمكن إجراء نفس الشيء في مشروع Javascript.
لذلك تخيل تطبيقًا صريحًا كلاسيكيًا:

هنا لدينا مورد "كتاب" وبعض نقاط النهاية الأساسية لـ CRUD. السؤال هو "كيف يمكنك إضافة وثائق Swagger باردة إلى واجهة برمجة التطبيقات هذه؟" أردت حقًا القيام بذلك باستخدام التعليقات التوضيحية من أجل إبقاء كل وثائق نقطة النهاية قريبة من نقطة النهاية نفسها.

هذا ما ستتمكن من فعله باستخدام mgr-swagger-express :
index.ts :

BookService.ts :

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

• في ملف الفهرس ، نقوم بإنشاء التطبيق السريع ، كالمعتاد. كما يجب علينا تهيئة جميع البرامج الوسيطة (يكون bodyParser هو الأكثر أهمية).
• بعد ذلك ندعو SET_EXPRESS_APP لتعيين كائن التطبيق على مستوى العالم. بهذه الطريقة ، سيتمكن mgr-swagger-express من إرفاق معالجات بنقاط النهاية
• بعد هذا فقط يمكننا استيراد الخدمة مع التعليقات التوضيحية. ليس من الضروري أن تكون فئة ، يمكن أن تكون مجرد وظائف.
• ثم نقوم بإنشاء مثيل لخدمتنا (أو استدعاء دالة init في حالة عدم استخدام الفصول الدراسية)
• وننشئ تهيئة swagger استنادًا إلى جميع التعليقات التوضيحية التي لدينا في المشروع ونعلقها على تطبيقنا باستخدام حزمة swagger-ui-express

داخل الخدمة ، هناك العديد من الأشياء الجارية ، ولكن دعونا نتوقف عن اثنين منهم فقط. كل شيء آخر يمكنك العثور عليه بسهولة في الريبو mgr-swagger-express:

• في المنشئ نسميه وظيفة addSwaggerDefinition . يسجل نموذج تبختر مع اسم معين. في حالتنا نعرّف BookDefinition تحت اسم Book من أجل الرجوع إليه بعد ذلك بواسطة #/definitions/Book
• يتم شرح جميع معالجات @GET @POST @PUT @DELETE . كلهم يأخذون في الوسائط كائنًا من النوع SwaggerEndpoint :
  

   path: string; auth?: string; description?: string; tags?: string[]; parameters?: SwaggerURLParameter[]; query?: SwaggerQueryParameter; body?: SwaggerBodyParameter; success?: SwaggerSuccessResponse; 

  
  

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

  
  يجب أن يكون لكل معالجات التوقيع التالي:
  

   (args: object, context: Context) => Promise<any> 

  
  

  يحتوي كائن args على جميع المعلمات التي تم توجيهها إلى نقطة النهاية. يمكن أن تكون معلمات URL (مثل book_id في مثالنا) أو معلمات الاستعلام أو حتى القيمة الأساسية.

  
  
  

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

  
  

  استنتاج

  
  

  الآن لدينا واجهة برمجة تطبيقات CRUD Express بسيطة مشروحة مع Swagger وواجهة تبديل اختيارية جميلة ، حيث توجد جميع تعريفات Swagger بالقرب من تطبيق نقطة النهاية. كالعادة - سعيد دائما أن يكون لديك أي ملاحظات! ️