API Architecture: Auto-Generating Interactive REST API Documentation with Swagger and OpenAPI

একটি জটিল সফটওয়্যার প্রোজেক্টে ব্যাকএন্ড এপিআই ডেভেলপ করার পর ফ্রন্টএন্ড টিম কিংবা বায়ারদের (Buyers) কাছে প্রতিটি এন্ডপয়েন্টের প্যারামিটার ও রেসপন্স স্ট্রাকচার বুঝিয়ে দেওয়া এক বিশাল ঝামেলার কাজ। পিডিএফ ফাইল বা সাধারণ টেক্সট ডক লিখে এপিআই ডকুমেন্টেশন শেয়ার করার সনাতন পদ্ধতি এখন ব্যাকডেটেড।

আধুনিক কাস্টম মডেল ও অ্যাপ্লিকেশন আর্কিটেকচারে ব্যবহৃত হয় **Swagger (OpenAPI Specification)**। এর মাধ্যমে কোডের ভেতরেই লাইভ ইন্টারঅ্যাক্টিভ ওয়েব প্যানেল অটো-জেনারেট হয়, যেখানে ক্লায়েন্টরা সরাসরি ব্রাউজার থেকেই "Try it out" বাটনে ক্লিক করে রিয়েল-টাইম এপিআই রিকোয়েস্ট টেস্ট করতে পারে।

১. নোড প্রজেক্টে Swagger ইন্টিগ্রেশন

আপনার এক্সপ্রেস (Express.js) অ্যাপ ডিরেক্টরিতে প্রয়োজনীয় কোর লাইব্রেরি দুটি ইনস্টল করে নিন:

npm install swagger-ui-express swagger-jsdoc --save

ধাপ ২: ডকুমেন্টেশন রুট ইঞ্জিন কোডিং (`app.js`)

আপনার মেইন ব্যাকএন্ড ইঞ্জিনে Swagger ডাইনামিক ইন্টারফেস মাউন্ট করার সম্পূর্ণ প্রফেশনাল মেথড কোড:

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

const app = express();
app.use(express.json());

// ১. ওপেনএপিআই মেটাডাটা স্কিমা কনফিগারেশন
const swaggerDefinitionOptions = {
    definition: {
        openapi: '3.0.0',
        info: {
            title: 'Ahyan Creations Core Engine REST API Gateway',
            version: '1.0.4',
            description: 'Centralized live synchronized infrastructure documentation endpoints.',
        },
        servers: [{ url: 'https://api.ahyancreations.top/v1' }],
    },
    apis: ['./app.js'], // যে ফাইলগুলোতে এন্ডপয়েন্ট কমেন্ট লেখা আছে
};

const swaggerSpecification = swaggerJsdoc(swaggerDefinitionOptions);
// ২. ইন্টারঅ্যাক্টিভ ড্যাশবোর্ড রুট মাউন্ট করা
app.use('/docs/api-explorer', swaggerUi.serve, swaggerUi.setup(swaggerSpecification));

/**
 * @openapi
 * /users/authenticate:
 * post:
 * summary: Request validated session token payload
 * requestBody:
 * required: true
 * content:
 * application/json:
 * schema:
 * type: object
 * properties:
 * apiKey:
 * type: string
 * responses:
 * 200:
 * description: Core sync authorization confirmed.
 */
app.post('/users/authenticate', (req, res) => {
    res.status(200).json({ status: "granted", token: "session_ax92_vault" });
});

app.listen(8080, () => console.log('API Engine active on port 8080. Explore docs at /docs/api-explorer'));