Czym jest nestjs-docfy

Warstwa narzędziowa NestJS, która wyprowadza dekoratory Swaggera z kontrolerów, bez utraty typowania i bez generowania innego wyniku OpenAPI.

Problem

Kontrolery NestJS udokumentowane przez @nestjs/swagger szybko gromadzą dziesiątki @ApiOperation, @ApiResponse, @ApiBody i @ApiTags, aż w końcu prawdziwa logika trasy ląduje zagrzebana pod metadanymi dokumentacji.

Rozwiązanie

nestjs-docfy wprowadza prostą konwencję: dla każdego *.controller.ts istnieje obok niego *.controller.docs.ts, trzymający całą dokumentację. To ten sam wzorzec, którego Nest już używa dla *.spec.ts.

  • Zero zmian w wygenerowanym wyniku OpenAPI.
  • Typowanie zachowane: plik towarzyszący importuje klasę kontrolera.
  • Wykrywanie przez require.cache, przed SwaggerModule.createDocument().

Przed i po

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

Wykrywanie pliku towarzyszącego zależy od require.cache, więc nie działa w runtime przy nest-cli.json skonfigurowanym z "webpack": true. Dla tych projektów zarejestruj zamiast tego plugin CLI, bo naprawia to automatycznie, u źródła, przy każdym buildzie.

Kiedy warto go użyć

Dobrze pasuje, gdy

  • Twoje API ma dziesiątki endpointów i kilka odpowiedzi na trasę.
  • Twój zespół traktuje OpenAPI jako wersjonowaną umowę.
  • Chcesz obiektywnych bramek CI (minimalne pokrycie, lintowanie dokumentacji).
AI-first

Towarzyszący pakiet docfy-ui renderuje referencję API z przyciskiem Copy for AI przy każdym endpoincie, idealnym do wklejania w LLM-y.