Documenting authentication

The swagger specification supports three types of authentication: basic, API key, and Oauth2. Nest.js provides two different methods that can be used to auto-configure the swagger document authentication information with the possibility for some settings to be overridden. Keep in mind, this is describing how users will authenticate with your application.

const swaggerOptions = new DocumentBuilder()
    .addBearerAuth('Authorization', 'header', 'apiKey')
    .build();

If your application is using basic authentication, the username and password as a base64 encoded string, or JSON web tokens (JWT), you will make use of the addBearerAuth configuration method. The example above uses the defaults Nest.js will use if no parameters are passed and establishes that the APIs use an API key like a JWT in the authorization header. The first parameter should contain the key/header where the authentication key should be provided. This same configuration should be used if users will be using an application key to access the APIs. Application keys are typically used by public API provides like Google Maps to limit access to APIs and associate an API call to a specific billing account.

const swaggerOptions = new DocumentBuilder()
    .addBearerAuth('token', 'query', 'apiKey')
    .addBearerAuth('appId', 'query', 'apiKey')
    .build();

This example describes two query parameters that must be included when calling APIs that require authentication. The second parameter describes where the authentication key should be provided, either as a header, query, or body parameter. The third parameter is the type of authentication. When using addBearerAuth, use apiKey or basic. In addition to basic and API key authentication, swagger also supports documenting an Oauth2 authentication flow.

const swaggerOptions = new DocumentBuilder()
    .addOAuth2('password', 'https://example.com/oauth/authorize', 'https://example.com/oauth/token', {
      read: 'Grants read access',
      write: 'Grants write access',
      admin: 'Grants delete access'
    })
    .build();

The first parameter to the addOAuth2 method is the OAuth2 flow the APIs use for authentication. In this example, we use the password flow to indicate the user should send a username and password to the API. You can also use implicit, application, and accessCode flow. The second and third parameters are the URLs where the user will authorize access to the APIs and request a refresh token, respectively. The last parameter is an object of all the scopes with descriptions that are available in the application.

For the blog application, we will keep the configuration simple and store the configuration in a new file in the shared/config directory. Having a central location will let us write the configuration once and implement multiple times.

export const swaggerOptions = new DocumentBuilder()
    .setTitle('Blog Application')
    .setDescription('APIs for the example blog application.')
    .setVersion('1.0.0')
    .setHost('localhost:3000')
    .setBasePath('/')
    .setSchemes('http')
    .setExternalDoc('For more information', 'http://swagger.io')
    .addTag('blog', 'application purpose')
    .addTag('nestjs', 'framework')
    .addBearerAuth('Authorization', 'header', 'apiKey')
    .build();

Our first implementation will use the configuration and the Nest.js swagger module to produce two new endpoints in our application: one to serve the swagger UI application and one to serve the swagger document as raw JSON.

@Body

You may have noticed in our example, the parameter we decorated with @Body had a type of UpdateCommentRequest. Your application may or may not have this class already. If not, let’s write it now.

export class UpdateCommentRequest {
    @ApiModelPropertyOptional()
    public body: string;
}

The request class is very basic and makes use of the first decorator we will cover from the Nest.js swagger module, @ApiModelPropertyOptional. This decorator informs the swagger module that the body property of the request class is an optional property that can be included in the request body when calling the API. This decorator is actually a shortcut for the @ApiModelProperty decorator. We could write our request class as:

export class UpdateCommentRequest {
    @ApiModelProperty({ required: false })
    public body: string;
}

However, if a property is optional, use the @ApiModelPropertyOptional decorator to save yourself some typing. Both decorators can take several additional properties in an object passed to the decorator that will further define the data model for the request body.

• description: A string that can be used to describe what the model property should contain or what it is used for.
• required: A boolean indicating if the model property is required. This only applies to the @ApiModelProperty decorator.
• type: The Nest.js swagger module will use the type associated with the model property or you can pass the type as any string or class value. If you use the isArray property, the type property should also be used. This property can also be used to pass any of the data types defined in the swagger specification.
• isArray: A boolean indicating if the model property should take an array of values. If the model does take an array of values, be sure to include this value in the decorator or the Nest.js swagger module will not know to represent the model property as an array.
• collectionFormat: Maps to the swagger specification collectionFormat setting. This is used to depict how a model properties array values should be formatted. For the request body, this property should probably not be used. Possible values are:
  • csv: comma separated values foo,bar
  • ssv: space separated values foo bar
  • tsv: tab separated values foo\tbar
  • pipes: pipe separated values foo|bar
  • multi: corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz. This is valid only for parameters in “query” or “formData”.
• default: The default value to be used for the model property in the swagger document. This value will also be used in the example provided in the Swagger UI. The type of this value will depend on the type of the model property but could be a string, number, or even an object.
• enum: If your model properties type is an enum, pass the same enum to the decorator using this property so the Nest.js swagger module can inject those enum values into the swagger document.
• format: If you use the type property with a data type described in the swagger specification, you may also need to pass the format for that data type. For example, a field that takes a number with multiple precision points, values after the decimal, the type would be integer but the format may be either float or double.
• multipleOf: A number indicating that the value passed in the model property should have a remainder of zero using the modulus operator. Setting this property in the decorator is only valid if the model properties type is number or the type provided to the decorator is integer.
• maximum: A number indicating that the value passed in the model property should be less than or equal to the given value to be valid. Setting this property in the decorator is only valid if the model properties type is number or the type provided to the decorator is integer. This property should not be used with exclusiveMaximum.
• exclusiveMaximum: A number indicating that the value passed in the model property should be less than the given value to be valid. Setting this property in the decorator is only valid if the model properties type is number or the type provided to the decorator is integer. This property should not be used with maximum.
• minimum: A number indicating that the value passed in the model property should be greater than or equal to the given value to be valid. Setting this property in the decorator is only valid if the model properties type is number or the type provided to the decorator is integer. This property should not be used with exclusiveMinimum.
• exclusiveMinimum: A number indicating that the value passed in the model property should be less than the given value to be valid. Setting this property in the decorator is only valid if the model properties type is number or the type provided to the decorator is integer. This property should not be used with minimum.
• maxLength: A number indicating that the value passed in the model property should a character length less than or equal to the given value to be valid. Setting this property in the decorator is only valid if the model properties type is string or the type provided to the decorator is string.
• minLength: A number indicating that the value passed in the model property should a character length more than or equal to the given value to be valid. Setting this property in the decorator is only valid if the model properties type is string or the type provided to the decorator is string.
• pattern: A string containing a JavaScript compatible regular expression. The value passed in the model property should match the regular expression to be valid. Setting this property in the decorator is only valid if the model properties type is string or the type provided to the decorator is string.
• maxItems: A number indicating that the value passed in the model property should an array length less than or equal to the given value to be valid. Setting this property in the decorator is only valid if the the isArray is also provided with a value of true.
• minItems: A number indicating that the value passed in the model property should an array length more than or equal to the given value to be valid. Setting this property in the decorator is only valid if the the isArray is also provided with a value of true.
• uniqueItems: A number indicating that the value passed in the model property should contain a set of unique array values. Setting this property in the decorator is only valid if the the isArray is also provided with a value of true.
• maxProperties: A number indicating that the value passed in the model property should contain a number of properties less than or equal to the given value to be valid. Setting this property in the decorator is only valid if the model property type is a class or object.
• minProperties: A number indicating that the value passed in the model property should contain a number of properties more than or equal to the given value to be valid. Setting this property in the decorator is only valid if the model property type is a class or object.
• readOnly: A boolean indicating the model property MAY be sent in the API response body, but should not be provided in the request body. Use this if you will be using the same data model class to represent the request and response bodies of an API.
• xml: A string containing XML that represent the format of the model property. Only use if the model property will contain XML.
• example: An example value to place in the swagger document. This value will also be used in the example provided in the Swagger UI and takes precedence over the default decorator property value.

The property that has been decorated with the @Body decorator should always have a type that is a class. Typescript interfaces cannot be decorated and do not provide the same metadata that a class with decorators can. If, in your application, any of your APIs have a property with the @Body decorator and an interface type, the Nest.js swagger module will not be able to correctly create the swagger document. In fact, the Swagger UI will most likely note display the body parameter at all.

@Param

The @Param decorator in our example contained a string value indicating which URL parameter to use for the comment parameter of our controller method. When the Nest.js swagger module encounters this decorator with the provided string, it is able to determine the name of the URL parameter and includes it in the swagger document along with the type provided for the method parameter. However, we could have also written the controller method without passing a string to the @Param decorator to get an object containing all of the URL parameters. If we do this, Nest.js will only be able to determine the names and types of the URL parameters if we use a class as the type for the comment parameter or use the @ApiImplicitParam decorator provided by the Nest.js swagger module on the controller method. Let’s create a new class to describe our URL params and see how it affects the swagger UI.

export class UpdateCommentParams {
    @ApiModelProperty()
    public entryId: string;

    @ApiModelProperty()
    public commentId: string;
}

In the UpdateCommentParams class, we have created a single property and used the @ApiModelProperty decorator so the Nest.js swagger module knows to include the properties with their types in the swagger document. Do not try to split the entryId out into it’s own class and extend it because the Nest.js swagger module will not be able to pickup the properties of the extended class. It is also important that the names of the properties used in the class matches the names used in the @Controller and @Put decorators. We can change our comment to use the new class.

@Put('comments/:commentId')
public async update(
    @Body() body: UpdateCommentRequest,
    @Param() params: UpdateCommentParams,
    @Query('testQuery') testQuery: string,
    @Headers('testHeader') testHeader: string
) {
}

We have changed the controller so that all path parameters are provided to the controller method’s params parameter as an object.

The swagger UI has been updated to show the comment put API takes two required URL parameters: entryId and commentId. If you will be writing APIs that use a single parameter in your method controller to hold all of the URL parameters, your preferred method of informing the Nest.js swagger module is what you should expect as URL parameters. Using a class as the type for your URL parameters not only informs the Nest.js swagger module of the URL parameters, it also helps in writing your application by providing type checking and code auto-completion.

If, however, you don’t want to make a new class to use as the type for your URL parameters, use an interface, or one or more of the URL parameters are in a Nest.js guard, or middleware, or in a custom decorator, but not in the controller method. You can still inform the Nest.js swagger module about the URL parameters using the @ApiImplicitParam decorator.

@Put('comments/:commentId')
@ApiImplicitParam({ name: 'entryId' })
public async update(
    @Body() body: UpdateCommentRequest,
    @Param('commentId') comment: string,
    @Query('testQuery') testQuery: string,
    @Headers('testHeader') testHeader: string
) {
}

If a path param is required to reach the controller method, but the controller method does not use the param specifically, the Nest.js swagger module will not include it in the swagger document unless the controller method is decorated with the @ApiImplicitParam decorator. Use the decorator once for each path parameter that is necessary to reach the controller method, but it isn’t used in the controller itself.

@Put('comments/:commentId')
@ApiImplicitParam({ name: 'entryId' })
@ApiImplicitParam({ name: 'commentId' })
public async update(
    @Body() body: UpdateCommentRequest,
    @Query('testQuery') testQuery: string,
    @Headers('testHeader') testHeader: string
) {
}

For example, the above controller, being a part of the comment controller, requires two path parameters: entryId and commentId. Since the controller does not contain any @Param decorators in the method parameters, @ApiImplicitParam is used to describe both path params.

The @ApiImplicitParam decorator can take several additional properties in an object passed to the decorator that will further define the URL parameter in the swagger document.

• name: A string containing the name of the URL parameter. This decorator property is the only one required.
• description: A string that can be used to describe what the URL parameter should contain or what it is used for.
• required: A boolean indicating if the URL parameter is required.
• type: A string containing one of the types defined in the swagger specification. Classes and objects should not be used.

@Query

The @Query decorator in our example contained a string value indicating which query parameter to use for the testQuery parameter of our controller method. When the Nest.js swagger module encounters this decorator with the provided string, it is able to determine the name of the query parameter and includes it in the swagger document along with the type provided for the method parameter. However, we could have also wrote the controller method without passing a string to the @Query decorator to get an object containing all the query parameters. If we do this, Nest.js will only be able to determine the names and types of the query parameters if we use a class as the type for the testQuery parameter or use the @ApiImplicitQuery decorator provided by the Nest.js swagger module on the controller method. Let’s create a new class to describe our query params and see how it affects the Swagger UI.

export class UpdateCommentQuery {
    @ApiModelPropertyOptional()
    public testQueryA: string;

    @ApiModelPropertyOptional()
    public testQueryB: string;
}

In the UpdateCommentQuery class, we have created two properties and used the @ApiModelPropertyOptional decorator so the Nest.js swagger module knows to include these properties with their types in the swagger document. We can change our comment and put the controller method to use the new class.

@Put('comments/:commentId')
public async update(
    @Body() body: UpdateCommentRequest,
    @Param('commentId') comment: string,
    @Query() queryParameters: UpdateCommentQuery,
    @Headers('testHeader') testHeader: string
) {
}

We have changed the controller so that all query parameters are provided to the controller method’s queryParameters parameter as an object.

The swagger UI has been updated to show the comment, and the put API takes two optional query parameters: testQueryA and testQueryB. If you will be writing APIs that will use a single parameter in your method controller to hold all of the query parameters, this should be your preferred method of informing the Nest.js swagger module you are expecting as query parameters. Using a class as the type for your query parameters not only informs the Nest.js swagger module of the query parameters, it also helps in writing your application by providing type checking and code auto-completion.

However, if you do not wish to make a new class to use as the type for your query parameters, you use an interface, or the query parameters are used in a Nest.js guard or middleware in a custom decorator, but not in the controller method. You can still inform the Nest.js swagger module about the query parameters using the @ApiImplicitQuery decorator.

@Put('comments/:commentId')
@ApiImplicitQuery({ name: 'testQueryA' })
@ApiImplicitQuery({ name: 'testQueryB' })
public async update(
    @Param('commentId') comment: string,
    @Body() body: UpdateCommentRequest,
    @Query() testQuery: any,
    @Headers('testHeader') testHeader: string
) {
}

If a query param is required to reach the controller method, but the controller method does not use the query param specifically, the Nest.js swagger module will not include it in the swagger document unless the controller method is decorated with the @ApiImplicitQuery decorator. Use the decorator once for each query parameter that is necessary to reach the controller method, but is not not used in the controller itself.

@Put('comments/:commentId')
@ApiImplicitQuery({ name: 'testQueryA' })
@ApiImplicitQuery({ name: 'testQueryB' })
public async update(
    @Param('commentId') comment: string,
    @Body() body: UpdateCommentRequest,
    @Headers('testHeader') testHeader: string
) {
}

For example, the above controller requires two query parameters: testQueryA and testQueryB. Since the controller does not contain any @Query decorators in the method parameters, @ApiImplicitQuery is used to describe both query params.

The @ApiImplicitQuery decorator can take several additional properties in an object passed to the decorator that will further define the query parameter in the swagger document.

• name: A string containing the name of the query parameter. This decorator property is the only one required.
• description: A string that can be used to describe what the query parameter should contain or what it is used for.
• required: A boolean indicating if the query parameter is required.
• type: A string containing one of the types defined in the swagger specification. Classes and objects should not be used.
• isArray: A boolean indicating if the model property should take an array of values. If the model does take an array of values, be sure to include this value in the decorator or the Nest.js swagger module will not know to represent the model property as an array.
• collectionFormat: Maps to the swagger specification collectionFormat setting. This is used to depict how a model properties array values should be formatted. Possible values are:
  • csv: comma separated values foo,bar
  • ssv: space separated values foo bar
  • tsv: tab separated values foo\tbar
  • pipes: pipe separated values foo|bar
  • multi: corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz. This is valid only for parameters in “query” or “formData”.

@Headers

The @Headers decorator in our example contained a string value indicating which request header value to use for the testHeader parameter of our controller method. When the Nest.js swagger module encounters this decorator with the provided string, it is able to determine the name of the request header and includes it in the swagger document along with the type provided for the method parameter. However, we could have also written the controller method without passing a string to the @Headers decorator to get an object containing all the request headers. If we do this, Nest.js will only be able to determine the names and types of the request headers if we use a class as the type for the testHeader parameter or use the @ApiImplicitHeader decorator provided by the Nest.js swagger module on the controller method. Let’s create a new class to describe our query params and see how it affects the swagger UI.

export class UpdateCommentHeaders {
    @ApiModelPropertyOptional()
    public testHeaderA: string;

    @ApiModelPropertyOptional()
    public testHeaderB: string;
}

In the UpdateCommentHeaders class, we have created two properties and used the @ApiModelPropertyOptional decorator so the Nest.js swagger module knows to include these properties with their types in the swagger document. We can change our comment put controller method to use the new class.

@Put('comments/:commentId')
public async update(
    @Body() body: UpdateCommentRequest,
    @Param('commentId') comment: string,
    @Query('testQuery') testQuery: string,
    @Headers() headers: UpdateCommentHeaders
) {
}

We have changed the controller so that all request parameters the controller expects are provided to the controller method’s queryParameters parameter as an object.

The swagger UI has been updated to show the comment put API expects two headers: testHeaderA and testHeaderB. If you will be writing APIs that will use a single parameter in your method controller to hold all of the expected headers, and this should be your preferred method of informing the Nest.js swagger module that you are expecting as query parameters. Using a class as the type for your expected headers not only informs the Nest.js swagger module of the headers, it also helps in writing your application by providing type checking and code auto-completion.

If, however, you do not wish to make a new class to use as the type for your expected headers, you use an interface, or the headers are used in a Nest.js guard or middleware or in a custom decorator, but not in the controller method. You can still inform the Nest.js swagger module about the query parameters using the @ApiImplicitHeader or the @ApiImplicitHeaders decorators.

@Put('comments/:commentId')
@ApiImplicitHeader({ name: 'testHeader' })
public async update(
    @Body() body: UpdateCommentRequest,
    @Param('commentId') comment: string,
    @Query('testQuery') testQuery: string,
    @Headers() headers: any
) {
}

If a header is required to reach the controller method, but the controller method does not use the header specifically. The Nest.js swagger module will not include it in the swagger document unless the controller method is decorated with the @ApiImplicitHeader or @ApiImplicitHeaders decorators. Use the @ApiImplicitHeader decorator once for each header, or the @ApiImplicitHeaders decorator once to describe all the headers. This is necessary to reach the controller method but it isn’t used in the controller itself.

@Put('comments/:commentId')
@ApiImplicitHeader({ name: 'testHeaderA' })
@ApiImplicitHeader({ name: 'testHeaderB' })
public async update(
    @Body() body: UpdateCommentRequest,
    @Param('commentId') comment: string,
    @Query('testQuery') testQuery: string,
) {
}

@Put('comments/:commentId')
@ApiImplicitHeader([
    { name: 'testHeaderA' },
    { name: 'testHeaderB' }
])
public async update(
    @Body() body: UpdateCommentRequest,
    @Param('commentId') comment: string,
    @Query('testQuery') testQuery: string,
) {
}

For example, the above controllers requires two headers: testHeaderA and testHeaderB. Since the controller does not contain and @Headers decorators in the method parameters, @ApiImplicitHeader, and @ApiImplicitHeaders that is used to describe both headers.

The @ApiImplicitHeader and @ApiImplicitHeaders decorators can take several additional properties in an object or array of objects, respectively, passed to the decorator that will further define the query parameter in the swagger document.

• name: A string containing the name of the header. This decorator property is the only one required.
• description: A string that can be used to describe what the header should contain or what it is used for.
• required: A boolean indicating if the header is required.

Note: the @ApiImplicitHeaders decorator is just a shortcut for using the @ApiImplicitHeader decorator multiple times. If you need to describe multiple headers, use @ApiImplicitHeaders. Also, you should not use these headers to describe authentication mechanics. There are other decorators for that.

Authentication

It is very likely that you will need to have some form of authentication in your application at some point. The blog example application uses a username and password combination to authenticate a user and provides a JSON web token to allow the user to access the APIs. However you decide to setup authentication, one thing is for sure: you will require either query parameters or headers to maintain an authentication state and you will most likely use Nest.js middleware or guards to check a user’s authentication state. You do this because writing that code in every controller method creates a lot of code duplication and would complicate every controller method.

If your application does require authentication, first, be sure your document settings are properly configured using the addOAuth2 or the addBearerAuth method. Refer back to the Document Settings section if you are unsure of what those methods do.

In addition to setting the authentication scheme for the swagger document, you should also use the ApiBearerAuth and/or the ApiOAuth2Auth decorators on the controller class or controller methods. When used on an entire controller class, these decorators inform the Nest.js swagger module that all controller methods require authentication. If not all controller methods require authentication, you will need to decorate the individual controller methods that do.

@Put('comments/:commentId')
@ApiBearerAuth()
public async update(
    @Body() body: UpdateCommentRequest,
    @Param('commentId') comment: string,
    @Query('testQuery') testQuery: string,
    @Headers('testHeader') testHeader: string
) {
}

This example depicts a single controller method, API, that requires a bearer token to be able to use the API.

@Put('comments/:commentId')
@ApiOAuth2Auth(['test'])
public async update(
    @Body() body: UpdateCommentRequest,
    @Param('commentId') comment: string,
    @Query('testQuery') testQuery: string,
    @Headers('testHeader') testHeader: string
) {
}

This example depicts a single controller method, API, that requires a specific set of OAuth2 roles to be able to use the API. The @ApiOAuth2Auth decorator takes an array of all the roles the user should have in order to have access to the API.

These decorators are used in conjunction with the ApiBearerAuth and ApiOAuth2Auth document settings to build a form the user can enter their credentials, either an API key or an Oauth key, and select their roles, if OAuth2 is being used, inside the swagger UI. These values are then passed in the appropriate places, either as query params or header values, when the user executes a specific API.

Clicking the Authorize button at the top of the swagger UI page will open the authorizations form. For a bearer token, log into the application and copy the auth token returned into the space provided in the swagger UI authorization. The token should be in the form of Bearer <TOKEN VALUE>. For OAuth2 authentication, enter your credentials and select the roles you are requesting. Clicking the Authorize button will save the credentials for use when executing the APIs in the swagger UI.