Kako generirate dokumentacijo API-ja s Swagger?

Question

Accepted Answer

NestJS se integrira s **Swagger/OpenAPI** preko `@nestjs/swagger` za **samodejno generiranje interaktivne dokumentacije API-ja** iz vašega koda — krmilnikov, poti, DTO-jev in dekoratorjev. Ustvari uporabniški vmesnik, ki ga je mogoče pregledovati, kjer lahko razvijalci raziskujejo in testirajo končne točke, ki so sinhronizirane s kodo.

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

Z nekaj vrsticami Swagger pregleda vašo aplikacijo in služi interaktivno dokumentacijo na `/api/docs` — samodejno se odraža vaše poti, parametri in DTO-ji.

## Dokumentiranje DTO-jev in odgovorov

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

Dekoratorji `@ApiProperty` dodajo opise, primere in omejitve poljem DTO-ja, kar bogatijo generirano shemo. (Marsikaj se samodejno izpelje iz tipov TypeScript in dekoratorjev `class-validator` — `CLI plugin` lahko zmanjša celo to uporabno kodo.)

## Dokumentiranje končnih točk

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

Dekoratorji kot so `@ApiTags`, `@ApiOperation` in `@ApiResponse` dodajo opise, skupno razvrstitev končnih točk in dokumentirajo možne odgovore.

## Kaj dobite

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

## Zakaj je to važno

Dokumentacija API-ja je nujno potrebna za kateri koli API-j, ki ga uporabljajo drugi — front-end ekipe, mobilne aplikacije, tretje osebe ali celo vašem prihodnjemu jazu — in integracija NestJS-a s Swagger-jem ustvari visokokakovostno dokumentacijo izjemno enostavno in zanesljivo.

Glavna prednost je, da je dokumentacija **samodejno generirana iz kode** (krmilniki, poti, DTO-ji in dekoratorji), zato ostane **sinhrona** z dejansko implementacijo namesto da bi zastarela kot ročno napisana dokumentacija neizogibno.

Razumevanje tega je dragoceno, ker odličn dokumentacija API-ja dramatično izboljša izkušnje razvijalcev in zmanjša težave pri integraciji: interaktivni **Swagger UI** omogoči uporabnikom, da raziskujejo in *testirajo* končne točke neposredno v brskalniku, in generirano **OpenAPI specifikacijo** lahko vodi generiranje odjemalskega SDK-ja in preizkušanje pogodb.

Znanje o nastavitvi Swagger-ja, obogatitvi dokumentacije z dekoratorji (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) in dokumentiranju avtentikacije je praktično, pogosto potrebno znanje — dobro dokumentirani API-ji so profesionalni standard in znamenje kakovosti back-end dela.

Ker NestJS izkoriša svojo strukturo dekorator/DTO za samodejno generiranje toliko (z minimalnim dodatnim naporom), ni opravičila, da ne bi imeli odličnih dokumentov, kar to zmogljivost naredi pomembno, visoko vrednostjo v resničnih NestJS projektih.