Swagger/OpenAPI जनरेशन Node.js (JavaScript) के लिए: उपकरण और उदाहरण

Swagger/OpenAPI जनरेशन Node.js (JavaScript) के लिए

Node.js पर आधुनिक वेब एप्लिकेशन विकसित करते समय, API के लिए स्पष्ट और अद्यतित दस्तावेज़ीकरण बनाना एक महत्वपूर्ण कार्य है। Swagger (OpenAPI) RESTful इंटरफेस का वर्णन करने का एक मानक है, जो स्वचालित रूप से इंटरैक्टिव दस्तावेज़ीकरण उत्पन्न करने, अनुरोधों का परीक्षण करने और क्लाइंट और सर्वर के बीच अनुबंध बनाए रखने की अनुमति देता है। इस लेख में, हम लोकप्रिय लाइब्रेरी का उपयोग करके Node.js एप्लिकेशन के लिए Swagger/OpenAPI दस्तावेज़ीकरण जनरेशन सेट अप करने का तरीका समझेंगे।

Swagger और OpenAPI क्या है?

OpenAPI Specification (पहले Swagger Specification के नाम से जाना जाता था) HTTP API का वर्णन करने का एक औपचारिक मानक है। यह अनुमति देता है:

• एंडपॉइंट, विधियों, पैरामीटर और प्रतिक्रिया प्रकारों को परिभाषित करना।
• स्वचालित रूप से क्लाइंट SDK उत्पन्न करना।
• इंटरैक्टिव दस्तावेज़ीकरण (Swagger UI) बनाना।
• अनुरोधों और प्रतिक्रियाओं को मान्य करना।

Node.js के लिए, OpenAPI एकीकरण को सरल बनाने वाली कई लाइब्रेरी हैं। आइए दो सबसे लोकप्रिय पर विचार करें: swagger-jsdoc और swagger-ui-express।

Node.js में Swagger जनरेशन के लिए लाइब्रेरी

मुख्य उपकरण:

• swagger-jsdoc — कोड में JSDoc टिप्पणियों को पार्स करता है और उनसे OpenAPI विशिष्टता एकत्र करता है।
• swagger-ui-express — उत्पन्न विशिष्टता को एक इंटरैक्टिव वेब पेज के रूप में प्रदर्शित करता है।
• @nestjs/swagger (यदि आप NestJS का उपयोग करते हैं) — स्वचालित जनरेशन के लिए डेकोरेटर।

हम Express.js के लिए swagger-jsdoc + swagger-ui-express के संयोजन पर ध्यान केंद्रित करेंगे।

स्थापना और कॉन्फ़िगरेशन

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: 'स्वचालित Swagger जनरेशन के साथ उदाहरण API',        },        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 */

Express में Swagger UI कनेक्ट करना

मुख्य एप्लिकेशन फ़ाइल (app.js या index.js) में जोड़ें:

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