Что такое nestjs-docfy

Слой инструментов для NestJS, который выносит декораторы Swagger из контроллеров, не теряя типизацию и не меняя итоговый документ OpenAPI.

Проблема

Контроллеры NestJS, задокументированные через @nestjs/swagger, быстро обрастают десятками @ApiOperation, @ApiResponse, @ApiBody и @ApiTags. Настоящая логика маршрута в итоге тонет под метаданными документации.

Решение

nestjs-docfy вводит простое соглашение: рядом с каждым *.controller.ts лежит *.controller.docs.ts, где и живёт вся документация. Тот же приём Nest уже применяет для *.spec.ts.

  • Итоговый документ OpenAPI не меняется никак.
  • Типизация сохраняется: companion-файл импортирует класс контроллера.
  • Обнаружение идёт через require.cache, до вызова SwaggerModule.createDocument().

До и после

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

Обнаружение companion-файлов опирается на require.cache, поэтому в рантайме оно не работает, когда в nest-cli.json задано "webpack": true. Для таких проектов зарегистрируйте плагин CLI: он чинит это автоматически, в корне проблемы, на каждой сборке.

Когда это подходит

Подходит, если

  • В вашем API десятки эндпоинтов и по нескольку ответов на маршрут.
  • Команда относится к OpenAPI как к версионируемому контракту.
  • Нужны объективные гейты в CI: минимальное покрытие, линтинг документации.
AI-first

Сопутствующий пакет docfy-ui рисует справочник API с кнопкой Copy for AI у каждого эндпоинта. Такой текст удобно вставлять в LLM.