M. ISLAM
OpenAPISwaggerAPI DocumentationNestJSBackend Engineering

Day 7 - OpenAPI & Swagger - API Document না করলে team-এর সবাই আপনাকে চিনবে 😤

June 13, 20265 min read30 Days Of Backend Engineering

একটা গল্প share করি। প্রায় ৩-৪ বছর আগের গল্প। তখন আমি fullstack developer হিসেবে কাজ করতাম। তখন একটা project-এর কাজ আসে, existing API already ready + সেটা integration করা লাগবে। Frontend design তো মোটামুটি ঠিকঠাকই ছিল। ঝামেলা বাধে integration করা নিয়ে।

আমার যে client ছিল, উনি আমাকে just একটা URL দিয়ে দিলো আর simple একটা body দিয়ে দিলো। তার সামনে try করলাম সুন্দরভাবে কাজ করলো। কিছুক্ষণ পরে আর কাজ করছে না। সেই client-কে message দিই। উনি আমাকে message দিয়ে সবকিছু বুঝিয়ে দিল। তখন বুঝতে পারি যে ঐটা আসলে একটা protected route ছিল, access করার জন্য একটা token লাগবে, যেটার জন্য user-কে login করতে হবে।

এই বিষয়টা আমাকে উনি বলেনি, কারণ যিনি API develop করেছিলেন তিনি এভাবেই বুঝিয়েছিলেন। পরে বিষয়টা আমি বুঝতে পারি। এরকম অনেক ঘটনা ঘটেছে। একটা project-এ এমন ছিল, তাদের authorization flow typical যেকোনো কিছু থেকে আলাদা। সেখানে অনেক question করে সবকিছু করতে হয়েছে।

এই unexpected issue যাতে create না হয় তার একটা solution আছে, API documentation।

কেন Document করবেন?

এবার আপনি একটু চিন্তা করেন। আপনি একটা backend API develop করেছেন। সেটা frontend-এ integration করতে হবে। এখন তারা যদি আমার মতো এরকম বিপদে পড়ে তাহলে কী পরিমাণ সময় নষ্ট হতে পারে তা একবার চিন্তা করুন।

এই জন্য API document করা খুবই important। যখন API documentation করবেন তখন সবকিছু সেখানে ready করা থাকবে: API URL, method, request body, response body, authentication flow etc.

এটা হলে, frontend developer-দের প্যারা নেয়া লাগবে না। Documentation দেখেই বুঝে যাবে যে আসলে কোন API-এর কী কাজ।

OpenAPI কী?

একটা জিনিস চিন্তা করেন, যখন কোনো একটা problem-এর solution করার জন্য, একাধিক ব্যক্তি একসাথে হয়। তখন একটা জিনিস খেয়াল করবেন যে একেক জন একেক রকমের কথা বলে থাকেন। সবার brain একভাবে চলে না। একটা সময় কেউ একজন একটা ভালো solution দেয়, যেটা ঐ problem-টা resolve করবে + extra কোনো problem create করবে না।

এখন engineer-দের মাঝেই কিন্তু এরকম problem হয়। API documentation-এর জন্য একেক জন একেক রকম idea দেন। কেউ MS Word-এর কথা বলবে, কারো আবার Notion পছন্দ, কারো আবার markdown লিখলে ভালো হয় etc. এখন ওপরের মতো একটা solution দরকার যা সব problem-কে solve করবে + যতটা possible কম problem create করবে।

সেই solution-টা হচ্ছে OpenAPI Specification (OAS)। এটা একটা standard format যার মধ্যে API-এর documentation করা হয়ে থাকে। এখানে YAML বা JSON format-এ সবকিছু লেখা হয়। OpenAPI Specification (OAS) নিয়ে Stack Learner YouTube channel-এর FullStack Army Playlist-এর ভেতরে একটা dedicated video আছে যেখানে এটা নিয়ে detail example-সহকারে সবকিছু দেখানো আছে।

এখানে একটা ছোট্ট problem আছে। সেটা হচ্ছে, document লিখে তো ফেললাম, কিন্তু use করবো কীভাবে? Engineer বা developer-রা তো এটা বুঝতে পারবে কিন্তু একটা simple developer বা একজন client যার এই YAML বা JSON সম্পর্কে knowledge নেই তিনি কীভাবে বুঝবেন, যে এখানে আছে টা কী?

এটার solution হচ্ছে Swagger UI। এটার কাজ হচ্ছে, আপনার design করা এই YAML-কে visual representation দিবে। আপনি visually একটা UI-এর মাধ্যমে সবকিছু দেখতে পারবেন + test-ও করে দেখতে পারবেন।

OpenAPI usages

OpenAPI specification basically একটা standard format। এই format-টা বলতে গেলে মোটামুটি fixed। যেকোনোভাবে এই format-এ text generate করতে পারলেই হচ্ছে।

এই কারণে এটা সব থেকে popular। কিছু use case দিলে বুঝতে পারবেন:

  • আপনি চাইলে comments থেকে এটা generate করতে পারবেন।
  • API hard code করে এটা generate করতে পারবেন।
  • আপনার API structure দিয়ে আপনি এই file generate করতে পারবেন। By the way, FastAPI by default এই কাজ করে থাকে।
আমি ৩টা বললাম। আপনি চাইলে এগুলো বাদেও আরও নানাভাবে এই file generation-এর কাজটা করতে পারবেন। এই কারণেই মূলত এটা অনেক বেশি popular। যে language decorator support করে সেখানে আপনি decorator use করে এই file-টা generate করে নিতে পারবেন। আপনার code organized থাকলো + কোনো কিছু change করলে আপনি same file-এ decorator-গুলো একটু update করে দিলে সব একদম perfect।

NestJS-এ দেখতে কেমন?

@ApiOperation({ summary: 'Get user by ID' })
@ApiParam({ name: 'id', type: Number })
@ApiResponse({ status: 200, type: UserDto })
@ApiResponse({ status: 404, description: 'User not found' })
@Get(':id')
getUser(@Param('id') id: number) {
  return this.userService.findOne(id);
}

এই decorators থেকে automatically Swagger doc generate হয়।

DTO Validation + Documentation একসাথে

export class CreateUserDto {
  @ApiProperty({ example: "monirul@example.com" })
  @IsEmail()
  email: string;

  @ApiProperty({ example: "John Doe", minLength: 2 })
  @IsString()
  @MinLength(2)
  name: string;
}

একটাই class - validation হচ্ছে, documentation হচ্ছে।

Design First Approach

ওপরে যেটা দেখলেন সেটা হচ্ছে, code-first approach, আগে কোড করে then documentation। এই documentation automatically generate হবে। Design first approach হচ্ছে এর ঠিক উল্টো। আগে পুরো documentation generate করা হবে, request, response, error format ইত্যাদি। সম্পূর্ণ documentation ready করে তারপর actual code করা হয়ে থাকে।

Design approach-এ hardcoded YAML file বা JSON file generate করা হয় যেটা OpenAPI compatible। এর UI tool দিয়ে সেটাকে serve করা হয়। এই UI দিয়ে API test-ও করা যায়। এক্ষেত্রে API testing tool যেমন Postman-এর দরকার খুব একটা হয় না।

আমি personally এই approach-টা খুব like করি। কারণ actual code করার সময় আমার request & response schema, API URL & method, validation, error response format ইত্যাদি নিয়ে কোনো চিন্তাই করা লাগে না। এতে focused way-তে দ্রুত API develop করা যায়। আর এখন তো AI আছে। AI-কে এই document + কিছু instruction দিয়ে দিলেই তো API develop করে দিতে পারবে। তবে AI-এর ওপর full depend না হয়ে অবশ্যই code check করা তারপর ship করাটা better।

Code-first vs Design-first Approach

Code-first এবং Design-first approach দুইটা কী তা বুঝতে পেরেছেন। এই দুইটা approach totally আলাদা purpose serve করে।

Actual conversation-এ যাওয়ার আগে নিচের এই trade-off table-টা লক্ষ্য করুন:

Code-FirstSpec-First
Initial velocity✅ Fast — just write code❌ Slower — spec takes upfront time
Changing a field✅ Change code, spec updates❌ Update spec, regenerate, update code
Prototyping✅ Great❌ Overhead
Stabilizing a public API❌ Risky✅ Forces discipline
ওপরের table দেখে হয়তো বলবেন, code-first-এ সবচেয়ে বেশি benefit দিচ্ছে তাহলে এটা better। কিন্তু একটু সামনের দিকে এগোলেই ঝামেলা শুরু হয়ে যায়।

Real world application-গুলোতে frontend এবং backend আলাদা আলাদাভাবে develop করা হয়। এখন code first-এর কথা চিন্তা করুন। যতক্ষণ পর্যন্ত আমার backend ready না হচ্ছে ততক্ষণ পর্যন্ত API use করা যাবে না। In fact আপনি চাইলেও mock করে use করতে পারবেন না। আর guess করে করতে গেলে double খাটনি হয়ে যেতে পারে।

মাত্রই mock করার কথা বললাম, in general development-এর সময় backend API-কে mock করে frontend-এ use করা হয়ে থাকে। যখন সবকিছু ready, then actual API integrate করা হয়ে থাকে। Mock করা হয়ে থাকে মূলত API-এর request & response body + method + status ইত্যাদিগুলো নিয়ে। মানে বিষয়টা এমন যে actual API ready হয়ে গেলে ওই same format-এ data response করবে। এখন code first approach-এ API ready হওয়ার পরে document generate হবে তখন এটা possible না। এর মানে হচ্ছে, API যতক্ষণ না ready হচ্ছে ততক্ষণ frontend-এ integrate করা possible না।

Code first-এর problem-গুলো design first approach দিয়ে solve করা যায়। Design-first-এ document generate করা হয় আগেই। এখন এই document দিয়ে mock করা possible। Same time-এ frontend backend দুইটাই একসাথে develop করা যায়। তবে এই approach-এর বড় problem হচ্ছে, যদি spec change হয় তাহলে manually documentation update করা লাগবে। Suppose একটা MVP-তে design first approach use করা হলে কী হতে পারে? ২ দিন পর পর documentation update, code update ইত্যাদি।

কখন কোনটা বেছে নেবেন?

Code-First:

  • Solo project বা internal tool
  • Rapid prototyping বা early-stage startup
  • API নিজের team member use করবে
**Spec-First:**
  • Public বা partner-দের use করার জন্য API
  • একাধিক team একসাথে backend ও frontend develop করবে
  • Versioning and breaking change management matter করলে
  • Microservices development-এ খুব useful

বটম লাইন

OpenAPI documentation একটা luxury না। এটা professional software development-এর basic requirement। একবার setup করলে team communication, onboarding, client SDK generation - সব সহজ হয়ে যায়।

আপনার team কি API document করে? কোন tool ব্যবহার করেন? কমেন্টে জানান! 👇

Back to publications