Bagaimana cara Anda menghasilkan dokumentasi API dengan Swagger?

Question

Accepted Answer

NestJS terintegrasi dengan **Swagger/OpenAPI** melalui `@nestjs/swagger` untuk **auto-generate dokumentasi API interaktif** dari kode Anda — controller, route, DTO, dan decorator. Ini menghasilkan UI yang dapat dijelajahi di mana developer dapat mengeksplorasi dan menguji endpoint, tetap sinkron dengan kode.

## Menyiapkan 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 memindai aplikasi Anda dan melayani dokumentasi interaktif di `/api/docs` — secara otomatis mencerminkan route, parameter, dan DTO Anda.

## Mendokumentasikan DTO dan response

```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` menambahkan deskripsi, contoh, dan batasan ke field DTO, memperkaya skema yang dihasilkan. (Banyak yang disimpulkan secara otomatis dari tipe TypeScript dan decorator `class-validator` — `CLI plugin` dapat mengurangi bahkan 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` menambahkan deskripsi, mengelompokkan endpoint, dan mendokumentasikan kemungkinan response.

## Yang Anda dapatkan

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

Dokumentasi API sangat penting untuk setiap API yang dikonsumsi oleh orang lain — tim frontend, aplikasi mobile, integrator pihak ketiga, atau bahkan diri Anda sendiri di masa depan — dan integrasi Swagger NestJS membuat menghasilkan dokumentasi berkualitas tinggi menjadi sangat mudah dan andal.

Keuntungan utamanya adalah dokumentasi **auto-generated dari kode** (controller, route, DTO, dan decorator), sehingga tetap **sinkron** dengan implementasi sebenarnya daripada ketinggalan zaman seperti dokumentasi yang ditulis tangan yang tidak dapat dihindari.

Memahaminya bernilai karena dokumentasi API yang baik secara dramatis meningkatkan pengalaman developer dan mengurangi gesekan integrasi: **Swagger UI** interaktif memungkinkan konsumen untuk mengeksplorasi dan *menguji* endpoint langsung di browser, dan **spesifikasi OpenAPI** yang dihasilkan dapat mendorong pembuatan SDK klien dan contract testing.

Mengetahui cara menyiapkan Swagger, memperkaya dokumentasi dengan decorator (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`), dan mendokumentasikan autentikasi adalah pengetahuan praktis yang sering diperlukan — API yang terdokumentasi dengan baik adalah standar profesional dan tanda kualitas pekerjaan back-end.

Karena NestJS memanfaatkan struktur decorator/DTO-nya untuk menghasilkan begitu banyak secara otomatis (dengan usaha minimal ekstra), ada sedikit alasan untuk tidak memiliki dokumentasi yang sangat baik, menjadikan ini kemampuan penting dan bernilai tinggi dalam proyek NestJS nyata.