Как генерировать документацию API с помощью Swagger?

Question

Accepted Answer

NestJS интегрируется с **Swagger/OpenAPI** через `@nestjs/swagger`, чтобы **автоматически генерировать интерактивную документацию API** из вашего кода — контроллеров, маршрутов, DTO и декораторов. Это создаёт доступный пользовательский интерфейс, где разработчики могут исследовать и тестировать эндпоинты, синхронизированные с кодом.

## Настройка 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
```

Всего несколькими строками Swagger сканирует ваше приложение и показывает интерактивную документацию по адресу `/api/docs` — автоматически отображая ваши маршруты, параметры и DTO.

## Документирование DTO и ответов

```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` добавляют описания, примеры и ограничения к полям DTO, обогащая сгенерированную схему. (Большая часть автоматически выводится из типов TypeScript и декораторов `class-validator` — `CLI плагин` может ещё больше снизить этот boilerplate.)

## Документирование эндпоинтов

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

Декораторы вроде `@ApiTags`, `@ApiOperation` и `@ApiResponse` добавляют описания, группируют эндпоинты и документируют возможные ответы.

## Что вы получаете

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

## Почему это важно

Документация API критически важна для любого API, используемого другими — фронтенд-командами, мобильными приложениями, сторонними интеграторами или даже вами в будущем — и интеграция Swagger в NestJS делает создание высококачественной документации удивительно простым и надёжным.

Ключевое преимущество в том, что документация **автоматически генерируется из кода** (контроллеров, маршрутов, DTO и декораторов), поэтому она остаётся **в синхронизации** с фактической реализацией, а не становится устаревшей, как это неизбежно происходит с написанной вручную документацией.

Понимание этого ценно, потому что хорошая документация API значительно улучшает опыт разработчика и снижает трения при интеграции: интерактивный **Swagger UI** позволяет потребителям исследовать и *тестировать* эндпоинты прямо в браузере, а сгенерированная **OpenAPI спецификация** может управлять генерацией клиентских SDK и контрактным тестированием.

Знание того, как настроить Swagger, обогатить документацию декораторами (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) и документировать аутентификацию — это практическое, часто требуемое знание — хорошо задокументированные API являются профессиональным стандартом и признаком качественной back-end работы.

Поскольку NestJS использует свою структуру декораторов/DTO для автоматической генерации большей части (с минимальными дополнительными усилиями), нет оснований не иметь отличную документацию, что делает это важной, высокоценной возможностью в реальных NestJS проектах.