Jak generować dokumentację API przy użyciu Swagger?

Question

Accepted Answer

NestJS integruje się z **Swagger/OpenAPI** za pośrednictwem `@nestjs/swagger` do **automatycznego generowania interaktywnej dokumentacji API** na podstawie kodu — kontrolerów, tras, DTO i dekoratorów. Tworzy przeglądalne interfejsy użytkownika, gdzie programiści mogą eksplorować i testować endpointy, utrzymywane w synchronizacji z kodem.

## Konfigurowanie 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 kilka linami kodu Swagger skanuje aplikację i serwuje interaktywną dokumentację pod adresem `/api/docs` — automatycznie odzwierciedlając trasy, parametry i DTO.

## Dokumentowanie DTO i odpowiedzi

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

Dekoratory `@ApiProperty` dodają opisy, przykłady i ograniczenia do pól DTO, wzbogacając wygenerowany schemat. (Wiele jest wnioskowane automatycznie z typów TypeScript i dekoratorów `class-validator` — `CLI plugin` może zmniejszyć nawet ten kod standardowy.)

## Dokumentowanie endpointów

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

Dekoratory takie jak `@ApiTags`, `@ApiOperation` i `@ApiResponse` dodają opisy, grupują endpointy i dokumentują możliwe odpowiedzi.

## Co dostajesz

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

## Dlaczego to ważne

Dokumentacja API jest niezbędna dla każdego API konsumowanego przez inne strony — zespoły frontendowe, aplikacje mobilne, integratory stron trzecich, lub nawet Ty w przyszłości — a integracja Swagger w NestJS sprawia, że tworzenie wysokiej jakości dokumentacji jest niezwykle łatwe i niezawodne.

Kluczową zaletą jest to, że dokumentacja jest **automatycznie generowana z kodu** (kontrolerów, tras, DTO i dekoratorów), więc pozostaje **w synchronizacji** z faktyczną implementacją, zamiast wychodzić z daty jak nieuchronnie robią to dokumenty pisane ręcznie.

Zrozumienie tego jest wartościowe, ponieważ dobra dokumentacja API dramatycznie poprawia doświadczenie deweloperów i zmniejsza tarcie integracyjne: interaktywny **Swagger UI** pozwala konsumentom eksplorować i *testować* endpointy bezpośrednio w przeglądarce, a wygenerowana **specyfikacja OpenAPI** może prowadzić generowanie zestawu SDK klienta i testowanie kontraktów.

Wiedza, jak skonfigurować Swagger, wzbogacić dokumentację dekoratorami (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) i dokumentować autentykację, jest praktyczną, często potrzebną wiedzą — dobrze udokumentowane API to standard zawodowy i znak charakterystyczny jakościowej pracy backendowej.

Ponieważ NestJS wykorzystuje strukturę dekoratora/DTO do generowania tak wiele automatycznie (z minimalnym dodatkowym wysiłkiem), nie ma wymówki, aby nie mieć doskonałej dokumentacji, czyniąc to ważną, wysokowartościową umiejętnością w rzeczywistych projektach NestJS.