Tag groups (x-tagGroups)

Organiseer controllers onder logische secties in tools die de x-tagGroups-extensie ondersteunen, met name ReDoc.

Groepen declareren

Geef group en tags mee aan docs():

users.controller.docs.ts
// users.controller.docs.ts
docs(UsersController, {
  classDecorators: [ApiTags('users')],
  group: 'Administration',
  tags: ['users'],
});

// roles.controller.docs.ts
docs(RolesController, {
  classDecorators: [ApiTags('roles')],
  group: 'Administration',
  tags: ['roles'],
});

tags moet overeenkomen met wat je al meegeeft aan ApiTags(). nestjs-docfy roept ApiTags niet zelf aan, het bouwt alleen de x-tagGroups-mapping uit wat je declareert.

Aan het document koppelen

Om de groepen daadwerkelijk aan het gegenereerde document te koppelen, roep je attachTagGroups() aan na SwaggerModule.createDocument():

main.ts
// main.ts
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { attachTagGroups } from 'nestjs-docfy';

const config = new DocumentBuilder().setTitle('My API').build();
const document = SwaggerModule.createDocument(app, config);

SwaggerModule.setup('api', app, attachTagGroups(document));

Gegenereerde extensie

yaml
x-tagGroups:
  - name: Administration
    tags:
      - users
      - roles

Meerdere docs()-aanroepen kunnen bijdragen aan dezelfde groep: tags worden samengevoegd en gededupliceerd. attachTagGroups() is een no-op (geeft het document ongewijzigd terug) wanneer geen enkele controller een group declareert.