توليد Swagger/OpenAPI لـ Node.js (JavaScript): الأدوات والأمثلة

توليد Swagger/OpenAPI لـ Node.js (JavaScript)

عند تطوير تطبيقات الويب الحديثة على Node.js، إحدى المهام الأساسية هي إنشاء توثيق واضح ومحدث لواجهات API. Swagger (OpenAPI) هو معيار لوصف واجهات RESTful، يتيح توليد توثيق تفاعلي تلقائيًا، واختبار الطلبات، والحفاظ على العقود بين العميل والخادم. في هذه المقالة، سنشرح كيفية إعداد توليد توثيق Swagger/OpenAPI لتطبيقات Node.js باستخدام المكتبات الشائعة.

ما هو Swagger و OpenAPI؟

مواصفات OpenAPI (المعروفة سابقًا باسم Swagger Specification) هي معيار رسمي لوصف HTTP API. تتيح:

• تحديد نقاط النهاية، والطرق، والمعاملات، وأنواع الاستجابات.
• توليد حزم SDK للعميل تلقائيًا.
• إنشاء توثيق تفاعلي (Swagger UI).
• التحقق من صحة الطلبات والاستجابات.

بالنسبة لـ Node.js، توجد عدة مكتبات تسهل دمج OpenAPI. سننظر في أشهر اثنتين: swagger-jsdoc و swagger-ui-express.

مكتبات توليد Swagger في Node.js

الأدوات الرئيسية:

• swagger-jsdoc — يحلل تعليقات JSDoc في الكود ويجمع منها مواصفات OpenAPI.
• swagger-ui-express — يعرض المواصفات المولدة كصفحة ويب تفاعلية.
• @nestjs/swagger (إذا كنت تستخدم NestJS) — أدوات تزيين للتوليد التلقائي.

سنركز على مجموعة swagger-jsdoc + swagger-ui-express لـ Express.js.

التثبيت والإعداد

قم بتثبيت الحزم اللازمة عبر npm:

npm install swagger-jsdoc swagger-ui-express

أنشئ ملف swagger.js مع الإعدادات الأساسية:

const swaggerJsdoc = require('swagger-jsdoc');const swaggerUi = require('swagger-ui-express');

const options = {    definition: {        openapi: '3.0.0',        info: {            title: 'My Node.js API',            version: '1.0.0',            description: 'مثال على API مع توليد Swagger تلقائي',        },        servers: [            { url: 'http://localhost:3000' },        ],    },    apis: ['./routes/*.js'], // المسار إلى الملفات التي تحتوي على نقاط النهاية};

const swaggerSpec = swaggerJsdoc(options);

module.exports = { swaggerUi, swaggerSpec };

إضافة تعليقات JSDoc إلى نقاط النهاية

الآن، في ملفات المسارات الخاصة بك (مثل routes/users.js)، أضف تعليقات بتنسيق OpenAPI:

/** * @openapi * /users: *   get: *     summary: الحصول على قائمة المستخدمين *     tags: [Users] *     parameters: *       - in: query *         name: limit *         schema: *           type: integer *         description: عدد المستخدمين (الافتراضي 10) *     responses: *       200: *         description: قائمة المستخدمين *         content: *           application/json: *             schema: *               type: array *               items: *                 $ref: '#/components/schemas/User' */router.get('/users', async (req, res) => {    const users = await getUsers(req.query.limit || 10);    res.json(users);});

وبالمثل، حدد نموذج البيانات:

/** * @openapi * components: *   schemas: *     User: *       type: object *       properties: *         id: *           type: integer *         name: *           type: string *         email: *           type: string */

ربط Swagger UI بـ Express

في الملف الرئيسي للتطبيق (app.js أو index.js)، أضف:

const express = require('express');const { swaggerUi,