タググループ(x-tagGroups)

x-tagGroups拡張(特にReDoc)に対応するツールで、コントローラーを論理的なセクションにまとめます。

グループを宣言する

groupとtagsを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は、すでにApiTags()に渡しているものと一致させる必要があります。nestjs-docfyはあなたの代わりにApiTagsを呼び出したりしません。宣言した内容からx-tagGroupsのマッピングを構築するだけです。

ドキュメントへ紐づける

実際にグループを生成されたドキュメントへ紐づけるには、SwaggerModule.createDocument()の後にattachTagGroups()を呼び出してください。

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));

生成される拡張

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

複数のdocs()呼び出しが同じグループに寄与できます。タグはマージされ重複が除去されます。どのコントローラーもgroupを宣言していない場合、attachTagGroups()は何もしません(ドキュメントを変更せずそのまま返します)。