Qué es nestjs-docfy

Una capa de tooling para NestJS que saca los decorators de Swagger de los controllers, sin perder tipado ni generar una salida OpenAPI distinta.

El problema

Los controllers de NestJS documentados con @nestjs/swagger acumulan rápidamente docenas de @ApiOperation, @ApiResponse, @ApiBody y @ApiTags, hasta el punto de que la lógica real de la ruta termina enterrada bajo metadata de documentación.

La solución

nestjs-docfy introduce una convención simple: por cada *.controller.ts, hay un *.controller.docs.ts a su lado, que contiene toda la documentación. Es el mismo patrón que Nest ya usa para *.spec.ts.

  • Cero cambios en la salida OpenAPI generada.
  • Tipado preservado: el archivo companion importa la clase controller.
  • Discovery vía require.cache, antes de SwaggerModule.createDocument().

Antes y después

users.controller.ts
@WithDocs()
@Controller('users')
export class UsersController {
  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.users.findOne(id);
  }
}
users.controller.docs.ts
docs(UsersController, {
  classDecorators: [ApiTags('Users')],
  methods: {
    findOne: [
      ApiParam({ name: 'id', type: String }),
      ApiOperation({ summary: 'Get user by id' }),
      ApiResponse({ status: 200, type: UserDto }),
      ApiResponse({ status: 404, description: 'User not found' }),
    ],
  },
});
webpack: true

El discovery del archivo companion depende de require.cache, así que no funciona en runtime con nest-cli.json configurado con "webpack": true. Para esos proyectos, registra en su lugar el plugin de CLI, ya que arregla esto automáticamente, de raíz, en cada build.

Cuándo usarlo

Encaja bien cuando

  • Tu API tiene docenas de endpoints y varias respuestas por ruta.
  • Tu equipo trata OpenAPI como un contrato versionado.
  • Quieres gates objetivos de CI (cobertura mínima, linting de docs).
AI-first

El paquete companion docfy-ui renderiza la referencia de la API con un botón Copy for AI en cada endpoint, ideal para pegar en LLMs.