Skip to content

Configuring Swagger

Jump to bottom
Mite Gjorgjiev edited this page Jan 28, 2025 · 2 revisions

Swagger is a powerful tool for documenting and testing APIs. In NestJS, you can easily integrate Swagger using the @nestjs/swagger package and swagger-ui-express. Below, I’ll explain how to set up Swagger in your NestJS application and configure it to work seamlessly with your Crudify-generated APIs.

Install Required Packages

First, install the necessary packages using npm or yarn:

npm install @nestjs/swagger swagger-ui-express

Configure Swagger in main.ts

In your main.ts file, configure Swagger using the DocumentBuilder and SwaggerModule. This setup allows you to customize the Swagger documentation to fit your application's needs.

Here’s an example configuration:

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

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

  // Swagger configuration
  const config = new DocumentBuilder()
    .setTitle('Crudify API') // Set the title of the API
    .setDescription('API generated by Crudify') // Set the description
    .setVersion('1.0') // Set the API version
    .build();

  // Create the Swagger document
  const document = SwaggerModule.createDocument(app, config);

  // Set up the Swagger UI endpoint
  SwaggerModule.setup('api', app, document, {
    swaggerOptions: {
      filter: true, // Enable filtering by tag
    },
  });

  await app.listen(3000);
}
bootstrap();

Adding @ApiTags to Group Endpoints in Swagger

To organize your API endpoints in Swagger, you can use the @ApiTags decorator from the @nestjs/swagger package. This decorator allows you to group related endpoints under a specific tag, making it easier for users to navigate and understand your API documentation.

Add @ApiTags to Your Controller

In your controller, use the @ApiTags decorator to specify a tag for all endpoints within that controller. For example, if you have a UserController, you can group all user-related endpoints under the users tag.

Here’s an example:

import { Controller } from '@nestjs/common';
import { ApiTags } from '@nestjs/swagger';
import { UserService } from './user.service';
import { User } from './user.entity';
import { Crudify, CrudifyController } from 'ncrudify';

@ApiTags('users') // Group all endpoints under the 'users' tag
@Crudify({
  model: {
    type: User, // Define your Mongoose model
  },
})
@Controller('users')
export class UserController extends CrudifyController<User> {
  constructor(public service: UserService) {
    super(service);
  }
}

Why Use @ApiTags?

The @ApiTags decorator provides the following benefits:

  1. Improved Organization: Endpoints are grouped logically, making it easier for users to find related operations.
  2. Better Readability: Tags act as categories in the Swagger UI, improving the overall readability of your API documentation.
  3. Filtering: If you enabled the filter: true option in the Swagger UI configuration, users can filter endpoints by tags for a more focused view.

Viewing Tags in Swagger UI

Once you’ve added @ApiTags to your controllers, the Swagger UI will display your endpoints grouped by their respective tags. For example:

  • users: Contains all user-related endpoints (e.g., GET /users, POST /users).
  • products: Contains all product-related endpoints (e.g., GET /products, POST /products).

This grouping makes it easier for users to navigate and test your API.

Explanation of the Configuration

1. DocumentBuilder

The DocumentBuilder is used to define the metadata for your Swagger documentation. It includes:

  • .setTitle('Crudify API'): Sets the title of your API.
  • .setDescription('API generated by Crudify'): Provides a description of your API.
  • .setVersion('1.0'): Specifies the version of your API.

You can also add additional configurations, such as:

  • .addTag('users'): Adds tags to group related endpoints.
  • .addBearerAuth(): Adds authentication support for your API.

2. SwaggerModule.createDocument(app, config)

This method generates the Swagger document based on the configuration and your application’s routes.

3. SwaggerModule.setup('api', app, document, { swaggerOptions: { filter: true } })

This method sets up the Swagger UI at the /api endpoint. The swaggerOptions object allows you to customize the Swagger UI behavior:

  • filter: true: Enables filtering by tag, making it easier for users to navigate your API documentation.

Why This Configuration Was Chosen

This setup was designed to provide users with the maximum configurability for their Swagger documentation. Here’s why:

  1. Customizable Metadata: The DocumentBuilder allows you to define the title, description, version, and tags for your API, making it easy to tailor the documentation to your application.
  2. Flexible Swagger UI Options: The swaggerOptions parameter in SwaggerModule.setup lets you customize the Swagger UI behavior, such as enabling filtering or adding custom styles.
  3. Integration with Crudify: By configuring Swagger in main.ts, you ensure that all routes, including those generated by Crudify, are automatically documented without additional effort.
  4. Clear Separation of Concerns: Keeping the Swagger configuration in main.ts ensures that your application’s bootstrap logic remains clean and focused.

Adding Tags and Authentication (Optional)

To further enhance your Swagger documentation, you can add tags and authentication support.

Example: Adding Tags

const config = new DocumentBuilder()
  .setTitle('Crudify API')
  .setDescription('API generated by Crudify')
  .setVersion('1.0')
  .addTag('users', 'Operations related to users') // Add a tag for user-related endpoints
  .addTag('products', 'Operations related to products') // Add a tag for product-related endpoints
  .build();

Example: Adding Bearer Authentication

const config = new DocumentBuilder()
  .setTitle('Crudify API')
  .setDescription('API generated by Crudify')
  .setVersion('1.0')
  .addBearerAuth() // Add Bearer token authentication support
  .build();

Accessing the Swagger UI

Once your application is running, you can access the Swagger UI by navigating to:

http://localhost:3000/api

Here, you’ll see all your API endpoints, grouped by tags (if configured), and you can test them directly from the browser.

Key Takeaways

  1. Install @nestjs/swagger and swagger-ui-express: These packages are required to integrate Swagger into your NestJS application.
  2. Configure Swagger in main.ts: Use the DocumentBuilder and SwaggerModule to set up Swagger documentation.
  3. Customize Swagger UI: Use swaggerOptions to enable filtering or other UI customizations.
  4. Maximize Configurability: This setup ensures that your Swagger documentation is flexible and integrates seamlessly with Crudify.

By following this guide, you can easily configure Swagger for your NestJS application and provide a user-friendly API documentation experience. Let me know if you need further assistance! 🚀

Clone this wiki locally