ਤੁਸ Swagger ਨਾਲ API documentation ਕਿਵੇਂ generate ਕਰਦੇ ਹੋ?

Question

Accepted Answer

NestJS **Swagger/OpenAPI** ਨਾਲ `@nestjs/swagger` ਦੁਆਰ integrate ਕਰਦਾ ਹੈ ਤਾਂ ਜੋ ਤੁਹਾਡੇ code — controllers, routes, DTOs, ਅਤੇ decorators — ਤੋਂ **auto-generate interactive API documentation** ਕੀਤੀ ਜਾ ਸਕੇ। ਇਹ ਇੱਕ browsable UI ਪ੍ਰਦਾਨ ਕਰਦਾ ਹੈ ਜਿੱਥੇ developers endpoints ਨੂੰ explore ਅਤੇ test ਕਰ ਸਕਦੇ ਹਨ، code ਦੇ ਨਾਲ ਸਮਕਾਲੀ ਰਹਿ ਕੇ।

## 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 ਨੂੰ scan ਕਰਦਾ ਹੈ ਅਤੇ `/api/docs` ਤੇ interactive docs ਫੁਰਨਾ ਕਰਦਾ ਹੈ — ਆਪਣੇ ਆਪ ਤੁਹਾਡੇ routes, parameters, ਅਤੇ DTOs ਨੂੰ ਦਰਸਾਉਂਦੇ ਹੋਏ।

## 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) {}
}
```

Decorators ਜਿਵੇਂ `@ApiTags`, `@ApiOperation`, ਅਤੇ `@ApiResponse` 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 ਲਈ essential ਹੈ ਜੋ ਦੂਸਰਿਆਂ ਦੁਆਰਾ consume ਕੀਤੀ ਜਾਂਦੀ ਹੈ — frontend teams, mobile apps, third-party integrators, ਜਾਂ ਖੱਤਿਯਾ ਤੁਹਾਡਾ ਭਵਿੱਖ ਵਾਲਾ ਆਪ — ਅਤੇ NestJS ਦਾ Swagger integration high-quality docs ਉਤਪਾਦਨ ਕਰਨਾ remarkably ਆਸਾਨ ਅਤੇ reliable ਬਣਾ ਦਿੰਦਾ ਹੈ।

ਮੁੱਖ ਫਾਇਦਾ ਇਹ ਹੈ ਕਿ documentation **code ਤੋਂ auto-generated ਹੈ** (controllers, routes, DTOs, ਅਤੇ decorators)، ਇਸਲਈ ਇਹ **ਸਮਕਾਲੀ** actual implementation ਦੇ ਨਾਲ ਰਹਿੰਦੀ ਹੈ ਬਜਾਏ hand-written docs ਵਾਂਗ ਬਾਹਰ ਵਲਣ ਤੋਂ।

ਇਸ ਨੂੰ ਸਮਝਣਾ valuable ਹੈ ਕਿਉਂਕਿ ਚੰਗੀ API docs developer experience ਨੂੰ dramatically ਬਿਹਤਰ ਬਣਾਉਂਦੇ ਹਨ ਅਤੇ integration friction ਨੂੰ ਘਟਾਉਂਦੇ ਹਨ: interactive **Swagger UI** consumers ਨੂੰ endpoints ਨੂੰ directly browser ਵਿੱਚ explore ਕਰਨ ਅਤੇ *test* ਕਰਨ ਦਿੰਦਾ ਹੈ، ਅਤੇ generated **OpenAPI spec** client SDK generation ਅਤੇ contract testing ਨੂੰ drive ਕਰ ਸਕਦਾ ਹੈ।

Javanica ਜਾਣਨਾ ਕਿ Swagger ਨੂੰ ਸੈੱਟ ਕਿਵੇਂ ਕਰਨਾ ਹੈ، docs ਨੂੰ decorators (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) ਨਾਲ enrich ਕਰਨਾ ਹੈ، ਅਤੇ authentication ਨੂੰ document ਕਰਨਾ ਹੈ practical، frequently-needed knowledge ਹੈ — well-documented APIs ਪੇਸ਼ੇਵਰ standard ਹਨ ਅਤੇ quality back-end work ਦੀ ਪਛਾਣ ਹਨ।

ਕਿਉਂਕਿ NestJS ਆਪਣੀ decorator/DTO structure ਨੂੰ leverage ਕਰਕੇ ਬਹੁਤ ਕੁਝ automatically generate ਕਰਦਾ ਹੈ (minimal extra effort ਨਾਲ)، excellent docs ਹੋਣ ਦਾ ਕੋਈ ਬਹਾਨਾ ਨਹੀਂ ਹੈ، ਇਹ real NestJS projects ਵਿੱਚ ਇੱਕ important، high-value capability ਬਣਾ ਦਿੰਦਾ ਹੈ।