आप Swagger के साथ API documentation कैसे generate करते हैं?

Question

Accepted Answer

NestJS `@nestjs/swagger` के माध्यम से **Swagger/OpenAPI** के साथ integrate होता है ताकि आपके code से **interactive API documentation auto-generate** की जा सके — controllers, routes, DTOs, और decorators। यह एक browsable UI बनाता है जहाँ developers endpoints को explore और test कर सकते हैं, और जो code के साथ sync में रहता है।

## 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 समृद्ध होता है। (बहुत कुछ automatically TypeScript types और `class-validator` decorators से 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 के लिए आवश्यक है जिसे दूसरे consume करते हैं — frontend teams, mobile apps, third-party integrators, या यहाँ तक कि आपका future self — और NestJS का Swagger integration high-quality docs बनाना उल्लेखनीय रूप से आसान और reliable बनाता है।

मुख्य लाभ यह है कि documentation **code से auto-generate** होती है (controllers, routes, DTOs, और decorators), इसलिए यह hand-written docs की तरह outdated होने के बजाय actual implementation के साथ **sync में** रहती है जैसा हाथ से लिखे docs अनिवार्य रूप से हो जाते हैं।

इसे समझना मूल्यवान है क्योंकि अच्छे API docs developer experience को नाटकीय रूप से बेहतर बनाते हैं और integration friction कम करते हैं: interactive **Swagger UI** consumers को endpoints को सीधे browser में explore और *test* करने देता है, और generated **OpenAPI spec** client SDK generation और contract testing को drive कर सकता है।

Swagger सेट अप करना, decorators (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) के साथ docs को समृद्ध करना, और authentication को document करना जानना व्यावहारिक, बारंबार आवश्यक ज्ञान है — well-documented APIs एक professional standard और quality back-end काम की पहचान हैं।

क्योंकि NestJS इतना कुछ automatically generate करने के लिए अपनी decorator/DTO structure का लाभ उठाता है (न्यूनतम अतिरिक्त प्रयास के साथ), excellent docs न होने का कोई बहाना नहीं है, जो इसे real NestJS projects में एक महत्वपूर्ण, high-value capability बनाता है।