Simplifying API Documentation with NestJS and OpenAPI (Swagger)

API documentation is a crucial aspect of building and maintaining RESTful APIs. In the world of NestJS, creating detailed and interactive documentation is made easy through the integration of the OpenAPI specification using Swagger. In this article, we’ll explore the steps to integrate Swagger into a NestJS application, providing a clean and interactive way to document your APIs.

Installation of @nestjs/swagger

To get started, you need to install the @nestjs/swagger package, which is the dedicated module for Swagger integration in NestJS. Use the following command:

$ npm install --save @nestjs/swagger

Bootstrap Swagger in main.ts

Once the installation is complete, open your main.ts file. This file serves as the entry point of your NestJS application. In this file, initialize Swagger using the SwaggerModule class provided by the @nestjs/swagger package.

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('Your API Title')

    .setDescription('Description of your API')

    .setVersion('1.0')

    .addTag('cats') // Optional: Add tags for better organization

    .build();

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

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

  await app.listen(3000);

}

bootstrap();

The DocumentBuilder helps structure the base document according to the OpenAPI Specification. It allows you to set properties such as title, description, version, and more. The createDocument method of the SwaggerModule class is used to generate the full document with all HTTP routes defined.

The SwaggerModule.setup method is then called to configure Swagger UI. It takes the path to mount the Swagger UI, the application instance, the document object, and optional configuration parameters.

Running the Application

Now, you can start your NestJS application using the following command:

$ npm run start

While the application is running, open your browser and navigate to http://localhost:3000/api. You should see the Swagger UI, which automatically reflects all your endpoints.

Additionally, you can generate and download a Swagger JSON file by navigating to http://localhost:3000/api-json.

Document Options

When creating a document, you can provide extra options to fine-tune the behavior. These options should be of type SwaggerDocumentOptions. For example:

const options: SwaggerDocumentOptions =  {

  operationIdFactory: (

    controllerKey: string,

    methodKey: string

  ) => methodKey

};

const document = SwaggerModule.createDocument(app, config, options);

You can customize the operation names generated by Swagger using the operationIdFactory.

Setup Options

Swagger UI can be further configured by passing the options object fulfilling the ExpressSwaggerCustomOptions interface as the fourth argument of the SwaggerModule.setup method.

const setupOptions: ExpressSwaggerCustomOptions = {

  explorer: true,

  // Other configuration options

};

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

These options allow customization of the Swagger UI appearance and behavior.

conclusion:

In conclusion, integrating Swagger into your NestJS application simplifies API documentation, making it interactive and easily accessible. By following these steps, you can enhance the developer experience and streamline the communication of your API specifications.

You can dive deeper into the subject by reading our A Comprehensive Guide to Querying JSON Columns in PostgreSQL