API Tags

API Tags are used to group related endpoints together in the Swagger UI dashboard, preventing a massive, unorganized list of routes and making the documentation easily navigable.

Overview

By default, if you do not use tags, Swagger UI will list every single endpoint in your application in one giant vertical list under a “default” heading. If you have 50 endpoints, this is impossible to read.

@ApiTags() allows you to logically group endpoints. Usually, one controller equals one tag (e.g., the UsersController is tagged as “Users”).

Key Concepts

• @ApiTags(): The decorator used to assign a tag to a controller or a specific method.
• Global Tags: Tags defined in main.ts using DocumentBuilder.addTag(). These are used to provide overarching descriptions for the tag categories themselves.

Code Examples

1. Tagging a Controller

Placing @ApiTags() at the top of a controller class automatically groups all methods inside that controller under that tag.

import { Controller, Get, Post } from '@nestjs/common';
import { ApiTags, ApiOperation } from '@nestjs/swagger';

// 1. All routes here will be grouped under the "Billing & Payments" section in Swagger UI
@ApiTags('Billing & Payments')
@Controller('billing')
export class BillingController {
  
  @Get('invoices')
  @ApiOperation({ summary: 'Get all invoices' })
  getInvoices() {
    return [];
  }

  @Post('checkout')
  @ApiOperation({ summary: 'Process a payment' })
  checkout() {
    return 'Success';
  }
}

2. Multiple Tags

You can assign multiple tags to a single controller or method. The endpoint will appear under both sections in the Swagger UI.

import { Controller, Post } from '@nestjs/common';
import { ApiTags, ApiOperation } from '@nestjs/swagger';

// This endpoint affects both the "Users" domain and the "Auth" domain
@ApiTags('Users', 'Authentication')
@Controller('users')
export class UsersController {
  
  @Post('reset-password')
  @ApiOperation({ summary: 'Request a password reset link' })
  resetPassword() {
    return 'Email sent';
  }
}

3. Adding Descriptions to Tags

Just tagging a controller as ‘Billing & Payments’ creates a section header. If you want to add descriptive text below that section header explaining what the billing domain handles, you do that in main.ts.

// main.ts
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('My API')
    // Provide descriptions for the tags used in your controllers
    .addTag('Billing & Payments', 'Endpoints related to Stripe integration, invoices, and subscriptions.')
    .addTag('Users', 'Operations for managing user profiles and settings.')
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}

Best Practices

• Controller-Level Tagging: Almost always apply @ApiTags() at the class level (above @Controller()). Avoid tagging individual methods unless a specific method truly belongs in a completely different conceptual group than the rest of the controller.
• Consistent Naming: Decide on a naming convention for tags. Plural nouns usually work best (e.g., Users, Products, Orders). Avoid mixing styles (e.g., User Operations, Products, Manage Orders).