Kaip generuoti API dokumentaciją naudojant Swagger?

Question

Accepted Answer

NestJS integruojasi su **Swagger/OpenAPI** per `@nestjs/swagger`, kad **automatiškai generuotų interaktyvią API dokumentaciją** iš jūsų kodo — kontrolerių, maršrutų, DTO ir dekoratorių. Tai sukuria naršomą sąsają, kurioje kūrėjai gali tyrinėti ir testuoti galines funkcijas, sinchronizuojamos su kodu.

## Swagger nustatymas

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

Keliomis eilutėmis Swagger nuskaito jūsų programą ir pateikia interaktyvią dokumentaciją adrese `/api/docs` — automatiškai atspindint jūsų maršrutus, parametrus ir DTO.

## DTO ir atsakymų dokumentavimas

```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` dekoratoriai prideda aprašymus, pavyzdžius ir apribojimus prie DTO laukų, praturtindami sugeneruotą schemą. (Daugelis yra automatiškai išvedami iš TypeScript tipų ir `class-validator` dekoratorių — `CLI įskiepis` gali dar labiau sumažinti šią standartiką.)

## Galinės funkcijos dokumentavimas

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

Dekoratoriai, tokie kaip `@ApiTags`, `@ApiOperation` ir `@ApiResponse`, prideda aprašymus, sugrupuoja galinis funkcijas ir dokumentuoja galimus atsakymus.

## Ką jūs gausite

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

## Kodėl tai svarbu

API dokumentacija yra būtina bet kuriam API, kurį naudoja kiti — priekinės dalies komandos, mobiliosios programos, trečiųjų šalių integracijos arba jūs pats ateityje — ir NestJS Swagger integracija daro aukštos kokybės dokumentacijos rašymą pastabiausiai lengvu ir patikimu.

Pagrindinį pranašumą yra tai, kad dokumentacija **automatiškai generuojama iš kodo** (kontroleriai, maršrutai, DTO ir dekoratoriai), todėl ji lieka **sinchronizuota** su aktualia realizacija, o ne nuolat atgal nuo parašytos rankoje dokumentacijos.

Jo supratimas yra vertingas, nes gera API dokumentacija dramatiškais būdais pagerina kūrėjų patirtį ir sumažina integracijos trintį: interaktyvi **Swagger UI** leidžia vartotojams tyrinėti ir *testuoti* galias funkcijas tiesiogiai naršyklėje, o sugeneruota **OpenAPI specifikacija** gali nukreipti kliento SDK generavimą ir sutarties testavimą.

Žinojimas, kaip nustatyti Swagger, praturtinti dokumentaciją dekoratoriais (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) ir dokumentuoti autentifikaciją yra praktiškas, dažnai reikalingas žinojimas — gerai dokumentuoti API yra profesionalus standartas ir kokybės back-end darbo žymė.

Nes NestJS naudoja savo dekoratoriaus/DTO struktūrą, kad automatiškai generuotų tiek daug (su minimaliu papildomu pastangu), nėra pasiteisinimo neturėti puikios dokumentacijos, todėl tai yra svarbi, didelės vertės galimybė tikruose NestJS projektuose.