Installing and Configuring Swagger in NestJS

Before our chroniclers begin writing the annals, we must prepare the proper tools - parchment, ink, and imperial seals. In NestJS, this means installing the

@nestjs/swagger

package and configuring the Swagger module.

Package Installation

The first step is to install the official Swagger package for NestJS:

1npm install @nestjs/swagger

The

@nestjs/swagger

package contains everything we need: decorators, a configuration module, and Swagger UI integration.

DocumentBuilder - The Architect of Chronicles

DocumentBuilder

is a class that allows you to build the API documentation configuration. It works like an architect who designs the structure of our annals:

1import { DocumentBuilder } from '@nestjs/swagger';
2
3const config = new DocumentBuilder()
4  .setTitle('Imperium Romanum API')
5  .setDescription('API documentation for managing the Roman Empire')
6  .setVersion('1.0')
7  .build();

DocumentBuilder Methods

| Method | Description | Example | |--------|-------------|---------| |

setTitle()

| Documentation name |

'Imperium API'

| |

setDescription()

| Project description |

'API for managing legions'

| |

setVersion()

| API version |

'1.0'

,

'2.3.1'

| |

addTag()

| Adds a tag (section) |

'Legiones'

| |

addBearerAuth()

| Configures JWT auth | Bearer options | |

setContact()

| Contact details | Name, URL, email | |

setLicense()

| API license | Name, URL | |

addServer()

| API server | URL, description | |

build()

| Finalizes configuration | Returns OpenAPI object |

SwaggerModule.setup() - Opening the Forum

After building the configuration, we need to "open the Forum" - that is, make the documentation available at a specific URL:

1import { NestFactory } from '@nestjs/core';
2import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
3import { AppModule } from './app.module';
4
5async function bootstrap() {
6  const app = await NestFactory.create(AppModule);
7
8  // 1. Build the documentation configuration
9  const config = new DocumentBuilder()
10    .setTitle('Imperium Romanum API')
11    .setDescription('API for managing provinces and legions of the Empire')
12    .setVersion('1.0')
13    .addTag('Legiones', 'Legion management')
14    .addTag('Provinciae', 'Province management')
15    .addTag('Tributum', 'Tax system')
16    .addBearerAuth()
17    .build();
18
19  // 2. Create the OpenAPI document
20  const document = SwaggerModule.createDocument(app, config);
21
22  // 3. Serve Swagger UI at the /api/docs path
23  SwaggerModule.setup('api/docs', app, document);
24
25  await app.listen(3000);
26}
27bootstrap();

After starting the application, Swagger UI will be available at

http://localhost:3000/api/docs

.

SwaggerModule.setup() Parameters

The

setup()

method accepts four arguments:

1. path - the URL path for documentation (e.g.,

   'api/docs'

   )
2. app - the NestJS application instance
3. document - the generated OpenAPI document
4. options (optional) - additional configuration options

1SwaggerModule.setup('api/docs', app, document, {
2  customSiteTitle: 'Chronicles of the Imperium API',
3  customfavIcon: '/favicon.ico',
4  swaggerOptions: {
5    persistAuthorization: true,
6    docExpansion: 'none',
7    filter: true,
8  },
9});

Extended DocumentBuilder Configuration

Here is a full configuration example with all options:

1const config = new DocumentBuilder()
2  .setTitle('Imperium Romanum API')
3  .setDescription('Complete API documentation of the Roman Empire')
4  .setVersion('2.0')
5  .setContact('Caesar Augustus', 'https://imperium.rome', 'caesar@rome.gov')
6  .setLicense('MIT', 'https://opensource.org/licenses/MIT')
7  .addServer('http://localhost:3000', 'Development server')
8  .addServer('https://api.imperium.rome', 'Production server')
9  .addTag('Legiones', 'Legion management endpoints')
10  .addTag('Provinciae', 'Province management endpoints')
11  .addBearerAuth(
12    { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
13    'JWT-auth',
14  )
15  .build();

Practical Exercise

Configure Swagger in the

main.ts

file of the Imperium project: