আপনি Swagger দিয়ে API ডকুমেন্টেশন কীভাবে তৈরি করবেন?

Question

Accepted Answer

NestJS **Swagger/OpenAPI** এর সাথে `@nestjs/swagger` এর মাধ্যমে ইন্টিগ্রেট করে আপনার কোড — কন্ট্রোলার, রুট, DTO এবং ডেকোরেটর থেকে **স্বয়ংক্রিয়ভাবে ইন্টারঅ্যাক্টিভ API ডকুমেন্টেশন তৈরি** করে। এটি একটি ব্রাউজযোগ্য UI তৈরি করে যেখানে ডেভেলপাররা এন্ডপয়েন্ট অন্বেষণ এবং পরীক্ষা করতে পারেন, যা কোডের সাথে সিঙ্ক রাখা হয়।

## Swagger সেটআপ করা

```ts
// main.ts
import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger";

const config = new DocumentBuilder()
  .setTitle("Users API")
  .setDescription("The users API documentation")
  .setVersion("1.0")
  .addBearerAuth()                       // document JWT auth
  .build();

const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup("api/docs", app, document);   // serve the UI at /api/docs
```

মাত্র কয়েকটি লাইনের সাথে, Swagger আপনার অ্যাপ্লিকেশন স্ক্যান করে এবং `/api/docs` এ ইন্টারঅ্যাক্টিভ ডকুমেন্টেশন পরিবেশন করে — স্বয়ংক্রিয়ভাবে আপনার রুট, প্যারামিটার এবং DTO প্রতিফলিত করে।

## DTO এবং রেসপন্স ডকুমেন্টিং

```ts
export class CreateUserDto {
  @ApiProperty({ example: "ann@example.com", description: "User email" })
  email: string;

@ApiProperty({ minLength: 8 })
  password: string;

@ApiPropertyOptional()                 // optional field in the docs
  age?: number;
}
```

`@ApiProperty` ডেকোরেটর DTO ফিল্ডে বর্ণনা, উদাহরণ এবং সীমাবদ্ধতা যোগ করে, যা জেনারেট করা স্কিমাকে সমৃদ্ধ করে। (TypeScript টাইপ এবং `class-validator` ডেকোরেটর থেকে অনেক কিছু স্বয়ংক্রিয়ভাবে অনুমান করা হয় — `CLI plugin` এমনকি এই বয়লারপ্লেট কমাতে পারে।)

## এন্ডপয়েন্ট ডকুমেন্টিং

```ts
@ApiTags("users")                        // group endpoints in the UI
@Controller("users")
export class UsersController {
  @Post()
  @ApiOperation({ summary: "Create a user" })
  @ApiResponse({ status: 201, description: "User created", type: User })
  @ApiResponse({ status: 400, description: "Invalid input" })
  create(@Body() dto: CreateUserDto) {}
}
```

`@ApiTags`, `@ApiOperation` এবং `@ApiResponse` এর মতো ডেকোরেটর বর্ণনা যোগ করে, এন্ডপয়েন্ট গ্রুপ করে এবং সম্ভাব্য রেসপন্স ডকুমেন্ট করে।

## আপনি কী পাবেন

```text
✓ Interactive UI (Swagger UI) — browse, read, and TEST endpoints in the browser
✓ Auto-generated, always in sync with the code (no separate doc to maintain)
✓ The OpenAPI spec (JSON) — usable to generate client SDKs, for contract testing, etc.
✓ Request/response schemas, validation rules, auth requirements all documented
```

## এটি কেন গুরুত্বপূর্ণ

যেকোনো API যা অন্যরা ব্যবহার করে — ফ্রন্টএন্ড টিম, মোবাইল অ্যাপ, তৃতীয় পক্ষের ইন্টিগ্রেটর বা এমনকি আপনার ভবিষ্যত সংস্করণ — API ডকুমেন্টেশন অপরিহার্য, এবং NestJS এর Swagger ইন্টিগ্রেশন উচ্চ মানের ডকুমেন্টেশন তৈরি করা অসাধারণভাবে সহজ এবং নির্ভরযোগ্য করে তোলে।

মূল সুবিধা হল যে ডকুমেন্টেশন **কোড থেকে স্বয়ংক্রিয়ভাবে তৈরি হয়** (কন্ট্রোলার, রুট, DTO এবং ডেকোরেটর), তাই এটি প্রকৃত বাস্তবায়নের সাথে **সিঙ্ক থাকে** হাতে লেখা ডকুমেন্টেশনের মতো পুরানো হয়ে যাওয়ার পরিবর্তে।

এটি বোঝা মূল্যবান কারণ ভালো API ডকুমেন্টেশন ডেভেলপার অভিজ্ঞতা নাটকীয়ভাবে উন্নত করে এবং ইন্টিগ্রেশন ঘর্ষণ কমায়: ইন্টারঅ্যাক্টিভ **Swagger UI** ভোক্তাদের ব্রাউজার থেকে সরাসরি এন্ডপয়েন্ট অন্বেষণ এবং *পরীক্ষা* করতে দেয়, এবং জেনারেট করা **OpenAPI spec** ক্লায়েন্ট SDK জেনারেশন এবং কন্ট্র্যাক্ট টেস্টিং চালিত করতে পারে।

সেটআপ করতে, ডেকোরেটর দিয়ে ডকুমেন্টেশন সমৃদ্ধ করতে (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) এবং অথেনটিকেশন ডকুমেন্ট করতে জানা ব্যবহারিক, ঘন ঘন প্রয়োজনীয় জ্ঞান — ভালোভাবে ডকুমেন্টেড API একটি পেশাদার মান এবং উচ্চমানের ব্যাকএন্ড কাজের একটি বৈশিষ্ট্য।

কারণ NestJS তার ডেকোরেটর/DTO কাঠামোকে কাজে লাগিয়ে স্বয়ংক্রিয়ভাবে এত কিছু জেনারেট করে (ন্যূনতম অতিরিক্ত প্রচেষ্টার সাথে), চমৎকার ডকুমেন্টেশন না রাখার জন্য সামান্য অজুহাত নেই, এটিকে প্রকৃত NestJS প্রকল্পে একটি গুরুত্বপূর্ণ, উচ্চ-মূল্যের সক্ষমতা তৈরি করে।