Como você gera documentação de API com Swagger?

Question

Accepted Answer

NestJS integra-se com **Swagger/OpenAPI** via `@nestjs/swagger` para **gerar automaticamente documentação interativa de API** a partir do seu código — controladores, rotas, DTOs e decoradores. Produz uma interface navegável onde desenvolvedores podem explorar e testar endpoints, mantida sincronizada com o código.

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

Com poucas linhas, Swagger analisa sua aplicação e serve docs interativos em `/api/docs` — refletindo automaticamente suas rotas, parâmetros e DTOs.

## Documentando DTOs e respostas

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

Decoradores `@ApiProperty` adicionam descrições, exemplos e restrições aos campos DTO, enriquecendo o esquema gerado. (Muito é inferido automaticamente a partir de tipos TypeScript e decoradores `class-validator` — o `CLI plugin` pode reduzir ainda mais esse boilerplate.)

## Documentando endpoints

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

Decoradores como `@ApiTags`, `@ApiOperation` e `@ApiResponse` adicionam descrições, agrupam endpoints e documentam possíveis respostas.

## O que você obtém

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

## Por que isso importa

Documentação de API é essencial para qualquer API consumida por terceiros — equipes frontend, aplicativos mobile, integradores terceirizados, ou mesmo você no futuro — e a integração Swagger do NestJS torna a produção de docs de alta qualidade notavelmente fácil e confiável.

A vantagem principal é que a documentação é **gerada automaticamente a partir do código** (controladores, rotas, DTOs e decoradores), então fica **sincronizada** com a implementação real em vez de desatualizar-se como docs escritos manualmente inevitavelmente fazem.

Entender isso é valioso porque boa documentação de API melhora dramaticamente a experiência do desenvolvedor e reduz atrito de integração: a **Swagger UI** interativa permite que consumidores explorem e *testem* endpoints diretamente no navegador, e o **spec OpenAPI** gerado pode impulsionar geração de SDK cliente e testes de contrato.

Saber como configurar Swagger, enriquecer os docs com decoradores (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) e documentar autenticação é conhecimento prático e frequentemente necessário — APIs bem documentadas são um padrão profissional e marca de qualidade no trabalho backend.

Porque NestJS aproveita sua estrutura decorator/DTO para gerar automaticamente tanto (com esforço mínimo extra), há pouca desculpa para não ter excelente documentação, tornando isso uma capacidade importante e de alto valor em projetos NestJS reais.