Nawa za ka samar da takardun API tare da Swagger?

Question

Accepted Answer

NestJS yana haɗi tare da **Swagger/OpenAPI** ta `@nestjs/swagger` don **samar ta atomatik takardun API masu aiki** daga kodanka — controllers, routes, DTOs, da decorators. Yana samar da UI da ake iya buɗe a ciki inda masu developer suke iya bincike da gwaji masu aiki, ana kiyaye shi cikin haɗin gida tare da kodanka.

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

Tare da wasu layi kaɗan, Swagger yana bincike aikinka kuma yana gabatar da takardun da ake aiki a `/api/docs` — ta atomatik yana nuna masu aiki, sigogi, da DTOs.

## Nuni DTOs da amsa

```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 suna ƙara bayanai, misalai, da ƙuntatawa ga filayen DTO, suna tahowa jadawaling da aka samar. (Yawancin abin yana fahimta ta atomatik daga nau'ikan TypeScript da `class-validator` decorators — `CLI plugin` na iya rage har da wannan boilerplate.)

## Nuni masu aiki

```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 kamar `@ApiTags`, `@ApiOperation`, da `@ApiResponse` suna ƙara bayanai, ƙungiya masu aiki, da nuni amsa mai yuwuwa.

## Abin da kake samu

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

## Me ya sa yana daci

Takardun API yawuyar za a ga don duk API da waje suke cinye — gidan gefen gida, aikace-aikacen mobile, masu haɗin kai na waje, ko ma ni nan gida — kuma NestJS's Swagger haɗin gida yana sanya samarwa takardun na inganci ma yawa madaidaiciyya ba iyaka. Babbar amfanin shine takardun **ta atomatik juje daga kodanka** (controllers, routes, DTOs, da decorators), don haka yana **haɗe** tare da aiwatarwa da gaske maimakon yin fitsari kamar takardun da aka rubuta ta hannu suke ɗan kafe.

## Misalan code