Swagger को साथ तपाइँ कसरी API documentation generate गर्नुहुन्छ?

Question

Accepted Answer

NestJS ले **Swagger/OpenAPI** को साथ `@nestjs/swagger` मार्फत एकीकृत गर्दछ तपाइँको कोड — controllers, routes, DTOs, र decorators — बाट **स्वचालित रूपमा इन्टरएक्टिभ API documentation** generate गर्न। यो एक ब्राउजेबल UI उत्पन्न गर्दछ जहाँ developers endpoints अन्वेषण र परीक्षण गर्न सक्छन्, कोडको साथ सिंक राखिएको।

## 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 तपाइँको app स्कैन गर्दछ र `/api/docs` मा इन्टरएक्टिभ docs provide गर्दछ — तपाइँको routes, parameters, र DTOs को साथ स्वचालित रूपमा प्रतिबिम्बित।

## DTOs र responses दस्तावेज गर्न

```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 को समृद्ध बनाउँछ। (धेरै कुरा TypeScript types र `class-validator` decorators बाट स्वचालित रूपमा अनुमान गरिन्छ — `CLI plugin` यो boilerplate पनि कम गर्न सक्छ।)

## Endpoints दस्तावेज गर्न

```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 को समूह गर्छन्, र सम्भावित responses को दस्तावेज गर्छन्।

## तपाइँ के पाउनुहुन्छ

```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 को लागि अनिवार्य छ जो अन्यले consume गर्छन् — frontend teams, mobile apps, third-party integrators, वा आफ्नै भविष्य आफै — र NestJS को Swagger integration उच्च-गुणस्तर को docs उत्पन्न गर्न असाधारण रूपमा सजिलो र विश्वस्त बनाउँछ।

मुख्य लाभ यो हो कि documentation **कोडबाट स्वचालित रूपमा generated** हुन्छ (controllers, routes, DTOs, र decorators), त्यसैले यो **सिंक मा रहन्छ** वास्तविक implementation को साथ हस्तलिखित docs को रूपमा अपरिहार्य रूपमा अप्रचलित हुने को बजाय।

यो बुझ्न मूल्यवान छ किनभने राम्रो API docs ले developers को अनुभव नाटकीय रूपमा सुधार गर्छ र integration friction कम गर्छ: इन्टरएक्टिभ **Swagger UI** ले consumers लाई endpoints अन्वेषण र ब्राउजर मा सीधा *परीक्षण* गर्न दिन्छ, र generated **OpenAPI spec** ले client SDK generation र contract testing ड्राइभ गर्न सक्छ।

Swagger सेटअप गर्न, decorators (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) को साथ docs लाई समृद्ध गर्न, र authentication दस्तावेज गर्न कसरी जान्न व्यावहारिक, बारम्बार-आवश्यक ज्ञान हो — राम्रोसँग दस्तावेज गरिएका APIs एक व्यावसायिक मानक र गुणस्तर back-end काम को एक सूचक हो।

NestJS लाई यसको decorator/DTO संरचना लाभ उठाउँदै इतनो अनेक कुरा स्वचालित रूपमा generate गर्न (न्यूनतम अतिरिक्त प्रयास को साथ), उत्कृष्ट docs न होने को लागि थोरै बहाना छ, यो वास्तविक NestJS projects मा एक महत्त्वपूर्ण, उच्च-मान क्षमता बनाउँछ।