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

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

Node.js पर REST API डेवलप करते समय, एक स्पष्ट और अप-टू-डेट डॉक्यूमेंटेशन बनाना एक अहम काम है। Swagger (अब OpenAPI) API को डिस्क्राइब करने का डी-फैक्टो स्टैंडर्ड बन गया है। इस आर्टिकल में, हम JavaScript (Node.js) प्रोजेक्ट्स में OpenAPI स्पेसिफिकेशन को ऑटोमैटिक जनरेट करने के मुख्य टूल्स पर चर्चा करेंगे।

OpenAPI क्या है और इसे क्यों जनरेट करें?

OpenAPI, RESTful API को JSON या YAML फॉर्मेट में डिस्क्राइब करने का एक स्पेसिफिकेशन है। इससे आप ये कर सकते हैं:

ऑटोमैटिक रूप से इंटरैक्टिव डॉक्यूमेंटेशन (Swagger UI) बनाना
अलग-अलग भाषाओं के लिए क्लाइंट SDK जनरेट करना
रिक्वेस्ट और रिस्पॉन्स की वैलिडेशन करना
टीमों के बीच इंटीग्रेशन को आसान बनाना

मैन्युअली स्पेसिफिकेशन लिखना एक समय लेने वाला काम है जो जल्दी पुराना हो जाता है। इसलिए Node.js के लिए ऐसे टूल्स डेवलप किए गए हैं जो कोड से OpenAPI जनरेट करते हैं।

Node.js में OpenAPI जनरेशन के मुख्य टूल्स

1. swagger-jsdoc

सबसे लोकप्रिय लाइब्रेरी जो कोड में JSDoc कमेंट्स को पार्स करके OpenAPI स्पेसिफिकेशन में बदल देती है। इसे npm से इंस्टॉल करें:

npm install swagger-jsdoc swagger-ui-express

Express के साथ उपयोग का उदाहरण:

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

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'मेरा API',
      version: '1.0.0',
      description: 'डॉक्यूमेंटेशन जनरेशन के साथ API का उदाहरण'
    },
    servers: [
      { url: 'http://localhost:3000' }
    ]
  },
  apis: ['./routes/*.js'] // एनोटेशन वाली फाइलों का पथ
};

const swaggerSpec = swaggerJsdoc(options);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

// एनोटेशन के साथ रूट का उदाहरण
/**
 * @openapi
 * /users:
 *   get:
 *     summary: यूज़र्स की लिस्ट प्राप्त करें
 *     tags: [Users]
 *     responses:
 *       200:
 *         description: सफल रिस्पॉन्स
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/components/schemas/User'
 */
app.get('/users', (req, res) => {
  res.json([{ id: 1, name: 'राहुल' }]);
});

app.listen(3000);

2. swagger-autogen

एक अधिक आधुनिक विकल्प जो कमेंट्स में एनोटेशन के आधार पर स्पेसिफिकेशन जनरेट करता है और डेटा टाइप्स को ऑटोमैटिक डिटेक्ट करता है। इंस्टॉलेशन:

npm install swagger-autogen

जनरेशन स्क्रिप्ट का उदाहरण:

const swaggerAutogen = require('swagger-autogen')();

const doc = {
  info: {
    title: 'मेरा API',
    description: 'API का विवरण'
  },
  host: 'localhost:3000',
  schemes: ['http']
};

const outputFile = './swagger-output.json';
const endpointsFiles = ['./app.js']; // रूट्स वाली मुख्य फाइल

swaggerAutogen(outputFile, endpointsFiles, doc).then(() => {
  require('./app.js'); // जनरेशन के बाद सर्वर शुरू करें
});

रूट्स में बस एक कमेंट जोड़ना होगा:

// #swagger.tags = ['Users']
// #swagger.description = 'यूज़र्स प्राप्त करने का एंडपॉइंट'
app.get('/users', (req, res) => {
  // #swagger.responses[200] = { description: 'यूज़र्स की सूची' }
  res.json([{ id: 1, name: 'प्रिया' }]);
});

3. express-oas-generator

एक लाइब्रेरी जो रिक्वेस्ट को इंटरसेप्ट करके एक्चुअल डेटा के आधार पर OpenAPI स्पेसिफिकेशन ऑटोमैटिक बनाती है। प्रोटोटाइप के लिए उपयुक्त:

npm install express-oas-generator

const express = require('express');
const expressOasGenerator = require('express-oas-generator');
const app = express();

expressOasGenerator.init(app, {}); // इनिशियलाइज़ेशन

app.get('/products', (req, res) => {
  res.json([{ id: 1, name: 'फ़ोन', price: 500 }]);
});

app.listen(3000);