Piye carane nggawe dokumentasi API nganggo Swagger?

Question

Accepted Answer

NestJS integrates with **Swagger/OpenAPI** via `@nestjs/swagger` to **auto-generate interactive API documentation** saka kode mu — controllers, routes, DTOs, lan decorators. Iku ngasilake UI sing bisa dibukak dening developers kanggo explore lan test endpoints, sing tetep sync karo kode.

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

Karo sawetara baris, Swagger scan app mu lan serve interactive docs ing `/api/docs` — automatically reflecting routes, parameters, lan DTOs mu.

## Dokumentasi DTOs lan responses

```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 nambahake descriptions, examples, lan constraints menyang DTO fields, ngayo-yayoken generated schema. (Akeh sing inferred otomatis saka TypeScript types lan `class-validator` decorators — `CLI plugin` bisa ngecilake malah boilerplate kuwi.)

## Dokumentasi endpoints

```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 kaya `@ApiTags`, `@ApiOperation`, lan `@ApiResponse` nambahake descriptions, ngelompokake endpoints, lan dokumentasi possible responses.

## Apa sing sampeyan pikul

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

Dokumentasi API iku essential kanggo API apa wae sing dikonsumsi dening liyan — frontend teams, mobile apps, third-party integrators, utawa malah sampeyan neng masa depan — lan NestJS Swagger integration nggawe ngasilake high-quality docs dadi remarkable easy lan reliable.

Kunci advantages yaiku dokumentasi **auto-generated saka kode** (controllers, routes, DTOs, lan decorators), mula iku tetep **in sync** karo implementasi aktual tinimbang drift out of date kaya hand-written docs sing pasti nganggur.

Ngerti iku valuable amarga good API docs dramatically improve developer experience lan reduce integration friction: **Swagger UI** interaktif ngadawahi consumers kanggo explore lan *test* endpoints directly ing browser, lan **OpenAPI spec** generated bisa drive client SDK generation lan contract testing.

Nguasai piye nyiapake Swagger, enrich docs nganggo decorators (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`), lan dokumentasi authentication yaiku practical, frequently-needed knowledge — well-documented APIs yaiku professional standard lan hallmark of quality back-end work.

Karena NestJS leverage decorator/DTO structure kanggo nggawe akeh otomatis (karo minimal extra effort), ora ana alasan kanggo ora duwe excellent docs, nggawe ini important, high-value capability ing real NestJS projects.