Como documentar APIs com Swagger/OpenAPI no NestJS

Problema

Documentação desatualizada em Notion enquanto o código mudou. Front-end quebra em silêncio por campo opcional que virou obrigatório. Onboarding lento para integradores.

Solução

Gerar OpenAPI a partir de DTOs e decorators no Nest (@nestjs/swagger), publicar /docs só em não-prod ou atrás de auth. Tratar o schema como contrato: versionamento e changelog.

Arquitetura

• DTOs com class-validator + @ApiProperty.
• Controllers com @ApiTags, @ApiOperation, @ApiResponse.
• CI: validar breaking changes com diff de schema (Spectral/OAS diff).

Código

import { ApiProperty } from "@nestjs/swagger";
import { IsUUID, IsInt, Min } from "class-validator";
 
export class CreateOrderDto {
  @ApiProperty({ format: "uuid" })
  @IsUUID()
  customerId!: string;
 
  @ApiProperty({ minimum: 1 })
  @IsInt()
  @Min(1)
  quantity!: number;
}

const config = new DocumentBuilder()
  .setTitle("Billing API")
  .setVersion("1.0")
  .addBearerAuth()
  .build();
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup("docs", app, document);

Performance

Gerar spec em build time para gateways; não expor introspection pesada em produção sem necessidade.

Melhorias futuras

Exemplos de request/response reais; SDK gerado (openapi-generator); Postman collection exportada no CI.

Conclusão

Boa documentação reduz custo de coordenação entre times. Recrutadores técnicos notam quando você fala de contrato, não só de endpoint.