Swagger सह API दस्तऐज कसे तयार करता?

Question

Accepted Answer

NestJS **Swagger/OpenAPI** सह `@nestjs/swagger` द्वारे **आपल्या कोडवरून परस्पर API दस्तऐज स्वयंचलितपणे तयार करते** — नियंत्रक, मार्ग, DTOs आणि decorator्स. हे एक ब्राउज करण्यायोग्य 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` येथे सेवा करते — आपल्या मार्ग, पॅरामीटर आणि DTOs स्वयंचलितपणे प्रतिबिंबित करते.

## DTOs आणि प्रतिक्रिया दस्तऐज करणे

```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` decorator्स DTO फील्डमध्ये विवरण, उदाहरणे आणि मर्यादा जोडतात, तयार केलेली स्कीमा समृद्ध करतात. (बहुतांश TypeScript प्रकार आणि `class-validator` decorator्सवरून स्वयंचलितपणे अनुमान केले जाते — `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` सारख्या decorator्स विवरण जोडतात, अंतबिंदू गटबद्ध करतात आणि संभाव्य प्रतिक्रिया दस्तऐज करतात.

## आपल्याला काय मिळते

```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 एकीकरण उच्च-गुणवत्तेचे दस्तऐज तयार करणे अद्भुत सहज आणि विश्वसनीय बनवते.

मुख्य फायदा असा आहे की दस्तऐज **कोडवरून स्वयंचलितपणे तयार होते** (नियंत्रक, मार्ग, DTOs आणि decorator्स), त्यामुळे हाताने लिहिलेल्या दस्तऐजांप्रमाणे वास्तविक अंमलबजावणीसह **सिंक मध्ये राहतात** आणि जुने होत नाहीत.

याचे समज महत्वाचे आहे कारण चांगले API दस्तऐज विकास अनुभव नाटकीयपणे सुधारतात आणि एकीकरण घर्षण कमी करतात: परस्पर **Swagger UI** ग्राहकांना ब्राउজरमध्ये अंतबिंदू शोधू आणि *परीक्षण* करू देते, आणि तयार केलेली **OpenAPI spec** ग्राहक SDK निर्माण आणि करार परीक्षण चालवू शकते.

Swagger कसे सेट अप करणे, decorator्स (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) सह दस्तऐज समृद्ध करणे आणि प्रमाणीकरण दस्तऐज करणे हे जाणून घेणे व्यावहारिक, वारंवार आवश्यक असलेले ज्ञान आहे — सुप्रलेखित API हे व्यावसायिक मानक आणि गुणवत्तेचे गुणचिन्ह आहेत.

NestJS त्याच्या decorator/DTO संरचनेचा लाभ घेऊन असे बरेच काही स्वयंचलितपणे तयार करते (कमीतकमी अतिरिक्त प्रयत्नाने), उत्कृष्ट दस्तऐज न करण्याचे कारण नाही, हे वास्तविक NestJS प्रकल्पांमध्ये एक महत्वाचे, उच्च-मूल्य क्षमता बनवते.