Kako generirate API dokumentaciju sa Swagger-om?

Question

Accepted Answer

NestJS se integrira sa **Swagger/OpenAPI** preko `@nestjs/swagger` kako bi **automatski generirao interaktivnu API dokumentaciju** iz vašeg koda — kontrolera, ruta, DTO-a i dekoratora. Proizvodi preglednu sučelje gdje razvojni inženjeri mogu istražiti i testirati krajnje točke, sve sinhronizovano s kodom.

## Postavljanje Swagger-a

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

Sa nekoliko redaka, Swagger skenira vašu aplikaciju i služi interaktivnu dokumentaciju na `/api/docs` — automatski reflektirajući vaše rute, parametre i DTO-e.

## Dokumentiranje DTO-a i odgovora

```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` dekoratori dodaju opise, primjere i ograničenja poljima DTO-a, obogaćujući generirani shemu. (Većina se automatski zaključuje iz TypeScript tipova i `class-validator` dekoratora — `CLI plugin` može smanjiti čak i ovu količinu repetitivnog koda.)

## Dokumentiranje krajnjih točaka

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

Dekoratori poput `@ApiTags`, `@ApiOperation` i `@ApiResponse` dodaju opise, grupiraju krajnje točke i dokumentiraju moguće odgovore.

## Što dobivate

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

## Zašto je to važno

API dokumentacija je neophodno za bilo koji API koji koriste drugi — timovi frontenda, mobilne aplikacije, integratori treće strane ili čak vi u budućnosti — a NestJS-eva Swagger integracija čini proizvodnju visokokvalitetne dokumentacije iznimno laganom i pouzdanom.

Glavna prednost je što je dokumentacija **automatski generirana iz koda** (kontrolera, ruta, DTO-a i dekoratora), pa ostaje **sinkronizirana** sa stvarnom implementacijom umjesto da zastarijevanja kao što se neizbježno događa ručno napisanim dokumentima.

Razumijevanje toga je vrijednosno jer dobra API dokumentacija dramatično poboljšava iskustvo razvojnih inženjera i smanjuje trenja pri integraciji: interaktivni **Swagger UI** omogućava korisnicima da istražuju i *testiraju* krajnje točke direktno u pregledniku, a generirana **OpenAPI specifikacija** može potaknuti generiranje SDK-a klijenta i testiranje ugovora.

Znanje kako postaviti Swagger, obogatiti dokumentaciju dekoratorima (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) i dokumentirati autentifikaciju je praktično, često potrebno znanje — dobro dokumentirani API-ji su profesionalni standard i oznaka kvalitete back-end rada.

Budući da NestJS iskorištava svoju strukturu dekoratora/DTO-a kako bi automatski generirao toliko mnogo (sa minimalnim dodatnim trudom), malo je opravdanja da nemate odličnu dokumentaciju, čineći ovo važnom, visokovrijednom mogućnošću u stvarnim NestJS projektima.