TypeScript's metadata reflection system has several limitations which make it impossible to, for instance, determine what properties a class consists of or recognize whether a given property is optional or required. However, some of these constraints can be addressed at compilation time. Nest provides a plugin that enhances the TypeScript compilation process to reduce the amount of boilerplate code required.
warning Hint This plugin is opt-in. If you prefer, you can declare all decorators manually, or only specific decorators where you need them.
The Swagger plugin will automatically:
- annotate all DTO properties with
- set the
requiredproperty depending on the question mark (e.g.
name?: stringwill set
- set the
enumproperty depending on the type (supports arrays as well)
- set the
defaultproperty based on the assigned default value
- set several validation rules based on
- add a response decorator to every endpoint with a proper status and
- generate descriptions for properties and endpoints based on comments (if
- generate example values for properties based on comments (if
Please, note that your filenames must have one of the following suffixes:
['.dto.ts', '.entity.ts'] (e.g.,
create-user.dto.ts) in order to be analysed by the plugin.
If you are using a different suffix, you can adjust the plugin's behavior by specifying the
dtoFileNameSuffix option (see below).
Previously, if you wanted to provide an interactive experience with the Swagger UI,
you had to duplicate a lot of code to let the package know how your models/components should be declared in the specification. For example, you could define a simple
CreateUserDto class as follows:
While not a significant issue with medium-sized projects, it becomes verbose & hard to maintain once you have a large set of classes.
By enabling the Swagger plugin, the above class definition can be declared simply:
The plugin adds appropriate decorators on the fly based on the Abstract Syntax Tree. Thus you won't have to struggle with
@ApiProperty decorators scattered throughout the code.
warning Hint The plugin will automatically generate any missing swagger properties, but if you need to override them, you simply set them explicitly via
With the comments introspection feature enabled, CLI plugin will generate descriptions and example values for properties based on comments.
For example, given an example
You must duplicate both description and example values. With
introspectComments enabled, the CLI plugin can extract these comments and automatically provide descriptions (and examples, if defined) for properties. Now, the above property can be declared simply as follows:
Using the CLI plugin
To enable the plugin, open
nest-cli.json (if you use Nest CLI) and add the following
You can use the
options property to customize the behavior of the plugin.
options property has to fulfill the following interface:
|DTO (Data Transfer Object) files suffix|
|Controller files suffix|
|If set to true, the module will reuse |
|If set to true, plugin will generate descriptions and example values for properties based on comments|
If you don't use the CLI but instead have a custom
webpack configuration, you can use this plugin in combination with
ts-jest (e2e tests)
To run e2e tests,
ts-jest compiles your source code files on the fly, in memory. This means, it doesn't use Nest CLI compiler and does not apply any plugins or perform AST transformations.
To enable the plugin, create the following file in your e2e tests directory:
With this in place, import AST transformer within your
jest configuration file. By default (in the starter application), e2e tests configuration file is located under the
test folder and is named