Swagger UI Customization - Decorating the Forum of Annals

Just as the Forum Romanum was decorated with columns, statues, and frescoes, our Swagger UI can be customized visually and functionally. NestJS offers many options for personalizing the documentation interface.

SwaggerModule.setup() Options

The fourth parameter of the

setup()

method allows for advanced configuration:

1SwaggerModule.setup('api/docs', app, document, {
2  customSiteTitle: 'Chronicles of Imperium Romanum',
3  customCss: '.swagger-ui .topbar { background-color: #8B0000; }',
4  swaggerOptions: {
5    persistAuthorization: true,
6    docExpansion: 'none',
7    filter: true,
8    showRequestDuration: true,
9    tryItOutEnabled: true,
10  },
11});

customSiteTitle - Name of the Notice Board

Changes the page title in the browser:

1SwaggerModule.setup('api/docs', app, document, {
2  customSiteTitle: 'Imperium API - Documentation',
3});

customCss - Frescoes on the Walls

Allows you to add custom CSS styles to Swagger UI:

1SwaggerModule.setup('api/docs', app, document, {
2  customCss: `
3    .swagger-ui .topbar { background-color: #8B0000; }
4    .swagger-ui .topbar-wrapper img { content: url('/logo.png'); }
5    .swagger-ui .info .title { color: #8B0000; }
6    .swagger-ui .btn.execute { background-color: #8B0000; }
7  `,
8});

swaggerOptions - Forum Regulations

Options controlling the behavior of Swagger UI:

| Option | Description | Default | |--------|-------------|---------| |

persistAuthorization

| Keep JWT token after refresh |

false

| |

docExpansion

| Default section expansion |

'list'

| |

filter

| Show search field |

false

| |

showRequestDuration

| Show response time |

false

| |

tryItOutEnabled

| Testing mode enabled by default |

false

| |

defaultModelsExpandDepth

| Model expansion depth |

1

| |

defaultModelExpandDepth

| Model field expansion depth |

1

|

1SwaggerModule.setup('api/docs', app, document, {
2  swaggerOptions: {
3    persistAuthorization: true,
4    docExpansion: 'none',
5    filter: true,
6    showRequestDuration: true,
7  },
8});

addBearerAuth - Authorization Configuration

Full JWT authentication configuration in Swagger:

1const config = new DocumentBuilder()
2  .setTitle('Imperium API')
3  .addBearerAuth(
4    {
5      type: 'http',
6      scheme: 'bearer',
7      bearerFormat: 'JWT',
8      name: 'JWT',
9      description: 'Enter JWT token',
10      in: 'header',
11    },
12    'JWT-auth',
13  )
14  .build();

After this configuration, an "Authorize" button will appear in Swagger UI where the user can enter their JWT token.

operationIdFactory - Operation Names

Every operation in OpenAPI has a unique

operationId

. You can control how they are generated:

1const document = SwaggerModule.createDocument(app, config, {
2  operationIdFactory: (controllerKey: string, methodKey: string) =>
3    methodKey,
4});

By default, NestJS generates

operationId

in the format

ControllerName_methodName

. The above setting will use only the method name.

createDocument Options

The

createDocument()

method accepts additional options:

1const document = SwaggerModule.createDocument(app, config, {
2  // Include only selected modules
3  include: [LegionModule, ProvinceModule],
4
5  // Schema nesting depth
6  deepScanRoutes: true,
7
8  // Custom operationId generator
9  operationIdFactory: (controllerKey, methodKey) => methodKey,
10
11  // Additional models to include
12  extraModels: [ErrorResponseDto, PaginatedResponseDto],
13});

Securing the Documentation

In a production environment, it is worth securing access to Swagger UI:

1import * as basicAuth from 'express-basic-auth';
2
3// Before SwaggerModule.setup()
4app.use(
5  '/api/docs',
6  basicAuth({
7    challenge: true,
8    users: { admin: 'imperiumSecret123' },
9  }),
10);
11
12SwaggerModule.setup('api/docs', app, document);

Practical Exercise

Configure advanced Swagger UI options for the Imperium project: