Swagger UI হল একটি টুল যা RESTful API ডকুমেন্টেশন তৈরি এবং প্রদর্শন করার জন্য ব্যবহৃত হয়। এটি OpenAPI Specification (OAS) ফরম্যাটে তৈরি করা API ডকুমেন্টেশন থেকে একটি ইন্টারেক্টিভ ডকুমেন্টেশন পেজ জেনারেট করে, যা ব্যবহারকারীদের API এপিআই কলগুলি সরাসরি পরীক্ষা করতে এবং তার ফিচারগুলো জানতে সাহায্য করে। Swagger UI ডকুমেন্টেশন তৈরি করতে OpenAPI Specification ফাইল লিখতে হয় যা JSON বা YAML ফরম্যাটে থাকে।
Swagger UI API ডেভেলপার এবং ব্যবহারকারীদের জন্য একটি চমৎকার টুল, কারণ এটি কেবল ডকুমেন্টেশন তৈরিতে সাহায্য করে না, বরং ব্যবহারকারীকে API এর সাথে সরাসরি ইন্টারঅ্যাক্ট করতে দেয়।
Swagger UI দিয়ে API Documentation তৈরি করার ধাপসমূহ
1. OpenAPI Specification (OAS) তৈরি করুন
Swagger UI ব্যবহারের জন্য প্রথমে আপনাকে একটি OpenAPI Specification (OAS) ফাইল তৈরি করতে হবে। এটি একটি JSON বা YAML ফাইল যা আপনার API-এর সমস্ত বিস্তারিত, যেমন এন্ডপয়েন্ট, রিকোয়েস্ট, রেসপন্স, এবং অন্যান্য কনফিগারেশন ধারণ করে।
OAS ফাইলের সাধারণ কাঠামো:
openapi: 3.0.0
info:
title: API Documentation
description: This is a sample API documentation
version: 1.0.0
servers:
- url: http://localhost:8080/api/v1
paths:
/users:
get:
summary: Get a list of users
description: This endpoint retrieves all the users.
responses:
'200':
description: Successfully fetched the list of users
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
email:
type: string
এটি কিভাবে কাজ করে:
- openapi: OpenAPI স্পেসিফিকেশন ভার্সন।
- info: API সম্পর্কিত তথ্য, যেমন শিরোনাম, বিবরণ এবং ভার্সন।
- servers: সার্ভার URL যেখান থেকে API রিকোয়েস্ট করা হবে।
- paths: API এন্ডপয়েন্ট এবং তাদের HTTP মেথড (GET, POST, PUT, DELETE) সহ অন্যান্য তথ্য।
2. Swagger UI ইনস্টল এবং কনফিগার করা
Swagger UI ব্যবহার করার জন্য, আপনাকে প্রথমে Swagger UI ইনস্টল এবং কনফিগার করতে হবে। এটি Node.js, Docker, বা CDN মাধ্যমে ইনস্টল করা যায়। এখানে কিভাবে Swagger UI ইনস্টল করা যায় তার কিছু পদ্ধতি আলোচনা করা হলো:
a. Swagger UI via CDN
আপনি যদি Swagger UI টুলকে সরাসরি ব্যবহার করতে চান, তবে CDN ব্যবহার করতে পারেন। নিচে একটি HTML ফাইলের উদাহরণ দেয়া হলো যা Swagger UI কে আপনার OpenAPI Specification ফাইলের সাথে লোড করে:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Swagger UI</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.52.5/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.52.5/swagger-ui-bundle.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.52.5/swagger-ui-standalone-preset.js"></script>
<script>
const ui = SwaggerUIBundle({
url: "path/to/your/openapi-spec.yaml", // এখানে আপনার OpenAPI Specification ফাইলের পাথ দিন
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
layout: "StandaloneLayout"
});
</script>
</body>
</html>
এই HTML ফাইলটি খুললে, Swagger UI আপনার OpenAPI Specification ফাইল লোড করে এবং আপনাকে API ডকুমেন্টেশন এবং ইন্টারেক্টিভ টেস্টিং ফিচারের মাধ্যমে API পরীক্ষা করতে দেয়।
b. Swagger UI Local Installation
Swagger UI কে আপনার লোকাল মেশিনে ইনস্টল করতে হলে, Node.js ব্যবহার করে এটি ইনস্টল করতে পারেন। এর জন্য নিচের পদক্ষেপগুলো অনুসরণ করতে হবে:
- Node.js এবং npm ইনস্টল করুন (যদি ইতিমধ্যে ইনস্টল না থাকে)।
টার্মিনালে নিচের কমান্ড দিয়ে Swagger UI ইনস্টল করুন:
npm install swagger-ui-expressএরপর, আপনার অ্যাপ্লিকেশন কোডে Swagger UI কনফিগার করুন:
const express = require('express'); const swaggerUi = require('swagger-ui-express'); const swaggerDocument = require('./path/to/your/openapi-spec.json'); // আপনার OAS ফাইলের পাথ const app = express(); app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument)); app.listen(3000, () => { console.log('Server is running on port 3000'); });- আপনার API ডকুমেন্টেশন দেখতে
http://localhost:3000/api-docsURL-এ যান।
3. Swagger UI ডকুমেন্টেশন কাস্টমাইজ করা
Swagger UI আপনাকে ডকুমেন্টেশন কাস্টমাইজ করার সুযোগও দেয়। আপনি swagger-ui প্যাকেজের মাধ্যমে CSS এবং JavaScript ব্যবহার করে ডকুমেন্টেশন দেখতে কিভাবে প্রদর্শিত হবে, সেটি কাস্টমাইজ করতে পারেন। এই কাস্টমাইজেশন অন্তর্ভুক্ত করতে পারে:
- Themeing: রঙ, ফন্ট, স্টাইল পরিবর্তন।
- Authorization: OAuth, API key ইত্যাদি সমর্থন কনফিগার করা।
- Deep Linking: বিভিন্ন অংশে সরাসরি লিঙ্ক করা।
4. Swagger UI ব্যবহার করে API টেস্টিং
Swagger UI একটি ইন্টারেক্টিভ টুল, যা ব্যবহারকারীদের API পরীক্ষা করতে সহায়তা করে। Swagger UI-তে যেকোনো এন্ডপয়েন্ট নির্বাচন করে ক্লায়েন্ট পারামিটার ইনপুট দিতে পারে এবং Send বাটন চাপলে রেসপন্স দেখা যায়।
- Input Parameters: ইনপুট প্যারামিটার (যেমন query parameters, headers) সরাসরি Swagger UI-তে যুক্ত করা যায়।
- Authentication: API যদি অথেনটিকেশন দাবি করে, তবে আপনি Swagger UI-তে Authorization ট্যাব থেকে API key বা OAuth token ইনপুট দিয়ে পরীক্ষা করতে পারবেন।
Conclusion
Swagger UI একটি শক্তিশালী টুল যা API ডকুমেন্টেশন তৈরি ও প্রদর্শনের প্রক্রিয়াকে সহজ করে তোলে। এটি OpenAPI Specification (OAS) ফাইল থেকে ইন্টারেক্টিভ ডকুমেন্টেশন তৈরি করে এবং ব্যবহারকারীদের সরাসরি API রিকোয়েস্ট ও রেসপন্স পরীক্ষা করার সুযোগ দেয়। Swagger UI একটি উন্নত এবং ব্যবহারকারী বান্ধব উপায় API ডকুমেন্টেশন তৈরি, পরীক্ষণ, এবং কাস্টমাইজেশন জন্য।
