Bagaimana anda menjana dokumentasi API dengan Swagger?

Question

Accepted Answer

NestJS berintegrasi dengan **Swagger/OpenAPI** melalui `@nestjs/swagger` untuk **menjana dokumentasi API interaktif secara automatik** daripada kod anda — controller, route, DTO, dan decorator. Ia menghasilkan UI yang boleh dilayari di mana pembangun boleh meneroka dan menguji endpoint, sentiasa selaras dengan kod.

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

Dengan beberapa baris, Swagger mengimbas aplikasi anda dan menyajikan dokumen interaktif di `/api/docs` — secara automatik mencerminkan route, parameter, dan DTO anda.

## Mendokumentasikan DTO dan respons

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

Decorator `@ApiProperty` menambah penerangan, contoh, dan kekangan pada medan DTO, memperkayakan skema yang dijana. (Banyak yang disimpulkan secara automatik daripada jenis TypeScript dan decorator `class-validator` — `CLI plugin` boleh mengurangkan walaupun boilerplate ini.)

## Mendokumentasikan endpoint

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

Decorator seperti `@ApiTags`, `@ApiOperation`, dan `@ApiResponse` menambah penerangan, mengumpulkan endpoint, dan mendokumentasikan kemungkinan respons.

## Apa yang anda dapat

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

## Mengapa ia penting

Dokumentasi API adalah penting untuk mana-mana API yang digunakan oleh orang lain — pasukan frontend, aplikasi mudah alih, pengintegrasi pihak ketiga, atau bahkan diri anda pada masa depan — dan integrasi Swagger NestJS menjadikan penghasilan dokumen berkualiti tinggi sangat mudah dan andal.

Kelebihan utama ialah dokumentasi **dijana secara automatik daripada kod** (controller, route, DTO, dan decorator), jadi ia kekal **selaras** dengan pelaksanaan sebenar dan bukannya menyimpang menjadi lapuk seperti yang pasti berlaku pada dokumen tulisan tangan.

Memahaminya berharga kerana dokumen API yang baik meningkatkan pengalaman pembangun secara mendadak dan mengurangkan geseran integrasi: **Swagger UI** interaktif membolehkan pengguna meneroka dan *menguji* endpoint terus dalam pelayar, dan **spec OpenAPI** yang dijana boleh memacu penjanaan SDK klien dan ujian kontrak.

Mengetahui cara menyediakan Swagger, memperkayakan dokumen dengan decorator (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`), dan mendokumentasikan pengesahan adalah pengetahuan praktikal yang kerap diperlukan — API yang didokumentasikan dengan baik ialah standard profesional dan ciri khas kerja back-end berkualiti.

Kerana NestJS memanfaatkan struktur decorator/DTO-nya untuk menjana begitu banyak secara automatik (dengan usaha tambahan yang minimum), tiada banyak alasan untuk tidak mempunyai dokumen yang cemerlang, menjadikan ini satu keupayaan yang penting dan bernilai tinggi dalam projek NestJS sebenar.