آپ Swagger کے ساتھ API documentation کیسے generate کرتے ہیں؟

Question

Accepted Answer

NestJS **Swagger/OpenAPI** کے ساتھ `@nestjs/swagger` کے ذریعے integrate کرتا ہے تاکہ **آپ کے code سے automatically interactive API documentation generate** ہو سکے — controllers، routes، DTOs، اور decorators سے۔ یہ ایک browsable UI تیار کرتا ہے جہاں developers endpoints کو explore اور test کر سکتے ہیں، جو code کے ساتھ synchronized رہتا ہے۔

## 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
```

صرف کچھ lines سے، Swagger آپ کی app کو scan کرتا ہے اور `/api/docs` پر interactive docs serve کرتا ہے — automatically آپ کے routes، parameters، اور DTOs کو reflect کرتے ہوئے۔

## DTOs اور responses کو document کرنا

```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` decorators DTO fields میں descriptions، examples، اور constraints شامل کرتے ہیں، جو generated schema کو enrich کرتے ہیں۔ (بہت کچھ TypeScript types اور `class-validator` decorators سے automatically infer ہوتا ہے — `CLI plugin` یہاں تک کہ اس boilerplate کو کم کر سکتا ہے۔)

## Endpoints کو document کرنا

```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` جیسے decorators descriptions شامل کرتے ہیں، endpoints کو group کرتے ہیں، اور ممکنہ responses کو document کرتے ہیں۔

## آپ کو کیا ملتا ہے

```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 documentation کسی بھی API کے لیے ضروری ہے جس کو دوسرے استعمال کریں — frontend teams، mobile apps، third-party integrators، یا حتیٰ کہ خود آپ کا مستقبل — اور NestJS کی Swagger integration high-quality docs تیار کرنا بہت آسان اور قابلِ اعتماد بناتی ہے۔

اہم فائدہ یہ ہے کہ documentation **code سے automatically generate** ہوتی ہے (controllers، routes، DTOs، اور decorators سے)، لہذا یہ **actual implementation کے ساتھ synchronized** رہتی ہے بجائے hand-written docs کے جو inevitably پرانے ہو جاتے ہیں۔

یہ سمجھنا قیمتی ہے کیونکہ اچھی API docs dramatically developer experience کو بہتر بناتے ہیں اور integration friction کو کم کرتے ہیں: interactive **Swagger UI** consumers کو endpoints کو directly browser میں explore اور *test* کرنے دیتا ہے، اور generated **OpenAPI spec** client SDK generation اور contract testing کو چلا سکتے ہیں۔

جاننا کہ Swagger کو کیسے سیٹ اپ کریں، docs کو decorators کے ساتھ enrich کریں (`@ApiProperty`، `@ApiTags`، `@ApiOperation`، `@ApiResponse`)، اور authentication کو document کریں — یہ practical، frequently-needed knowledge ہے — well-documented APIs ایک professional standard ہیں اور quality back-end work کی علامت ہیں۔

کیونکہ NestJS اپنے decorator/DTO structure کو leverage کرتے ہوئے بہت کچھ automatically generate کرتا ہے (minimal extra effort کے ساتھ)، excellent docs نہ ہونے کا کوئی بہانہ نہیں ہے، یہ ایک اہم، high-value capability بناتے ہوئے حقیقی NestJS projects میں۔