توليد Swagger/OpenAPI لجافا سكريبت (Node.js) — الأدوات والمكتبات

توليد Swagger/OpenAPI لجافا سكريبت (Node.js)

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

ما هو OpenAPI ولماذا يتم توليده؟

OpenAPI هي مواصفة لوصف RESTful API بتنسيق JSON أو YAML. تتيح ما يلي:

\n
• إنشاء توثيق تفاعلي تلقائيًا (Swagger UI)
\n
• توليد حزم SDK للعملاء بلغات مختلفة
\n
• التحقق من صحة الطلبات والاستجابات
\n
• تبسيط التكامل بين الفرق
\n

كتابة المواصفات يدويًا هي عملية شاقة وسرعان ما تصبح قديمة. لذلك، تم تطوير أدوات لـ Node.js تقوم بتوليد OpenAPI من الكود.

الأدوات الرئيسية لتوليد OpenAPI في Node.js

1. swagger-jsdoc

المكتبة الأكثر شيوعًا، والتي تقوم بتحليل تعليقات JSDoc في الكود وتحويلها إلى مواصفات OpenAPI. يتم تثبيتها عبر npm:

npm install swagger-jsdoc swagger-ui-express

مثال على الاستخدام مع Express:

const swaggerJsdoc = require('swagger-jsdoc');\nconst swaggerUi = require('swagger-ui-express');\nconst express = require('express');\nconst app = express();\n\nconst options = {\n  definition: {\n    openapi: '3.0.0',\n    info: {\n      title: 'API الخاص بي',\n      version: '1.0.0',\n      description: 'مثال API مع توليد التوثيق'\n    },\n    servers: [\n      { url: 'http://localhost:3000' }\n    ]\n  },\n  apis: ['./routes/*.js'] // المسار إلى الملفات التي تحتوي على التعليقات التوضيحية\n};\n\nconst swaggerSpec = swaggerJsdoc(options);\napp.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));\n\n// مثال على مسار مع تعليق توضيحي\n/**\n * @openapi\n * /users:\n *   get:\n *     summary: الحصول على قائمة المستخدمين\n *     tags: [Users]\n *     responses:\n *       200:\n *         description: استجابة ناجحة\n *         content:\n *           application/json:\n *             schema:\n *               type: array\n *               items:\n *                 $ref: '#/components/schemas/User'\n */\napp.get('/users', (req, res) => {\n  res.json([{ id: 1, name: 'إيفان' }]);\n});\n\napp.listen(3000);

2. swagger-autogen

بديل أكثر حداثة، يقوم بتوليد المواصفات بناءً على التعليقات التوضيحية ويحدد أنواع البيانات تلقائيًا. التثبيت:

npm install swagger-autogen

مثال على سكريبت التوليد:

const swaggerAutogen = require('swagger-autogen')();\n\nconst doc = {\n  info: {\n    title: 'API الخاص بي',\n    description: 'وصف API'\n  },\n  host: 'localhost:3000',\n  schemes: ['http']\n};\n\nconst outputFile = './swagger-output.json';\nconst endpointsFiles = ['./app.js']; // الملف الرئيسي مع المسارات\n\nswaggerAutogen(outputFile, endpointsFiles, doc).then(() => {\n  require('./app.js'); // تشغيل الخادم بعد التوليد\n});

في المسارات، يكفي إضافة تعليق:

// #swagger.tags = ['Users']\n// #swagger.description = 'نقطة نهاية للحصول على المستخدمين'\napp.get('/users', (req, res) => {\n  // #swagger.responses[200] = { description: 'قائمة المستخدمين' }\n  res.json([{ id: 1, name: 'آنا' }]);\n});

3. express-oas-generator

مكتبة تعترض الطلبات وتقوم ببناء مواصفات OpenAPI تلقائيًا بناءً على البيانات الفعلية. مناسبة للنماذج الأولية:

npm install express-oas-generator

const express = require('express');\nconst expressOasGenerator = require('express-oas-generator');\nconst app = express();\n\nexpressOasGenerator.init(app, {}); // التهيئة\n\napp.get('/products', (req, res) => {\n  res.json