If I understood your question you need to specify in your controller which bearer token you are using. In your case:

// swagger config
...
const config = new DocumentBuilder()
    .setTitle('SWAGGER API')
    .setVersion('1.0.0')
    .addBearerAuth(
      { 
        // I was also testing it without prefix 'Bearer ' before the JWT
        description: `[just text field] Please enter token in following format: Bearer <JWT>`,
        name: 'Authorization',
        bearerFormat: 'Bearer', // I`ve tested not to use this field, but the result was the same
        scheme: 'Bearer',
        type: 'http', // I`ve attempted type: 'apiKey' too
        in: 'Header'
      },
      'access-token', // This name here is important for matching up with @ApiBearerAuth() in your controller!
    )
    .build();
...

and in your controller:

@Get('/some-route')
@ApiBearerAuth('access-token') //edit here
@UseGuards(JwtAuthenticationGuard)
getData(
  @ReqUser() user: User,
): void {
  this.logger.warn({user});
}
Answer from Andrea Mugnai on Stack Overflow
🌐
Reddit
reddit.com › r/nestjs_framework › how to add custom headers in swaggerui (@nestjs/swagger)
r/Nestjs_framework on Reddit: How to add custom headers in SwaggerUI (@nestjs/swagger)
November 1, 2021 -

Hello,

I am currently not able to get SwaggerUI to correctly handle a custom header:

// in route, the following Header is set
  @ApiHeader({
    name: 'X-Custom-Header',
    description: 'Some custom header',
    required: false,
  })
...
@Post('route')
routeHandler(@Headers('X-Custom-Header') customHeader?: string) {..}

The header is correctly showing up in SwaggerUI in the route, but any value passed in is ignored / not added as header.

The following request is sent:

curl -X 'POST' \
  'http://$host/route' \
  -H 'accept: application/json' \
  -d ''

What am I missing?

Appreciate the help, thanks in advance!

Top answer
1 of 4
19

If I understood your question you need to specify in your controller which bearer token you are using. In your case:

// swagger config
...
const config = new DocumentBuilder()
    .setTitle('SWAGGER API')
    .setVersion('1.0.0')
    .addBearerAuth(
      { 
        // I was also testing it without prefix 'Bearer ' before the JWT
        description: `[just text field] Please enter token in following format: Bearer <JWT>`,
        name: 'Authorization',
        bearerFormat: 'Bearer', // I`ve tested not to use this field, but the result was the same
        scheme: 'Bearer',
        type: 'http', // I`ve attempted type: 'apiKey' too
        in: 'Header'
      },
      'access-token', // This name here is important for matching up with @ApiBearerAuth() in your controller!
    )
    .build();
...

and in your controller:

@Get('/some-route')
@ApiBearerAuth('access-token') //edit here
@UseGuards(JwtAuthenticationGuard)
getData(
  @ReqUser() user: User,
): void {
  this.logger.warn({user});
}
2 of 4
1

You can ignore the name and param of @ApiBearerAuth()

const config = new DocumentBuilder()
.setTitle('SWAGGER API')
.setVersion('1.0.0')
.addBearerAuth(
  { 
    // I was also testing it without prefix 'Bearer ' before the JWT
    description: `[just text field] Please enter token in following format: Bearer <JWT>`,
    name: 'Authorization',
    bearerFormat: 'Bearer', // I`ve tested not to use this field, but the result was the same
    scheme: 'Bearer',
    type: 'http', // I`ve attempted type: 'apiKey' too
    in: 'Header'
  }
)
.build();

And in your controller:

@Get('/some-route')
@ApiBearerAuth() //edit here
@UseGuards(JwtAuthenticationGuard)
getData(
   @ReqUser() user: User,
): void {
  this.logger.warn({user});
}
Discussions

Global Headers for all Controllers (nestJs swagger) - Stack Overflow
Is there a way to globally add required headers to all endpoints / controllers in NestJS? There is a controller bound decorator @ApiHeader. Is there a way to apply this to all endpoints? More on stackoverflow.com
🌐 stackoverflow.com
how to custom request headers
i need add options to request headers like this: swagger-api/swagger-ui#3605 https://alexdunn.org/2018/06/29/adding-a-required-http-header-to-your-swagger-ui-with-swashbuckle/ More on github.com
🌐 github.com
2
November 5, 2019
Unable to add headers to a route in swagger documentation.
I looked inside the file api-header.decorator.d.ts in node_modules/@nestjs/swagger/dist/decorators More on github.com
🌐 github.com
2
February 10, 2020
Authorization header not sent via the Swagger UI
I'm using Passport/Jwt auth with a Nest API and all works very well when I hit the API via Postman (or any other external client I can control the headers). When using the Swagger UI generated by this package the Authorization header is never sent. I can utilize the 'Authorize' UI to 'Login' ... More on github.com
🌐 github.com
11
June 11, 2018
🌐
GitHub
github.com › nestjs › swagger › issues › 2906
Swagger decorator @ApiHeader is not including header on request · Issue #2906 · nestjs/swagger
April 2, 2024 - @Controller('template') export class TemplateController { @Get('test') @ApiHeader({ name: 'accept', }) async test(@Headers('accept') acceptHeader: string) { return `ok: ${acceptHeader}`; } } https://codesandbox.io/p/devbox/green-cache-5xjgvc · Just create a new NestJS project and add a new Controller like TemplateController above. Expect that Swagger UI to include the proper accept value on request.
Author   nestjs
🌐
GitHub
github.com › nestjs › swagger › issues › 376
how to custom request headers · Issue #376 · nestjs/swagger
November 5, 2019 - i need add options to request headers like this: swagger-api/swagger-ui#3605 https://alexdunn.org/2018/06/29/adding-a-required-http-header-to-your-swagger-ui-with-swashbuckle/
Author   nestjs
🌐
GitHub
github.com › nestjs › swagger › issues › 557
Unable to add headers to a route in swagger documentation. · Issue #557 · nestjs/swagger
February 10, 2020 - import { ParameterObject } from '../interfaces/open-api-spec.interface'; import { SwaggerEnumType } from '../types/swagger-enum.type'; export interface ApiHeaderOptions extends Omit<ParameterObject, 'in'> { enum?: SwaggerEnumType; } export declare function ApiHeader(options: ApiHeaderOptions): any; export declare const ApiHeaders: (headers: ApiHeaderOptions[]) => MethodDecorator; Adding name property to the interface ApiHeaderOptions fixed the issue. export interface ApiHeaderOptions extends Omit<ParameterObject, 'in'> { enum?: SwaggerEnumType; name?: string; } Nest version: 6.11.6 @nestjs/swagger version: 4.2.1 Node version: 12.14.0 Platform: Linux
Author   nestjs
🌐
PROGRESSIVE CODER
progressivecoder.com › home › blog › a simple guide to nestjs swagger operations
A Simple Guide to NestJS Swagger Operations - PROGRESSIVE CODER
February 10, 2023 - In this post, we will look at NestJS Swagger Operations. Operations are basically HTTP methods such as GET, POST, PUT, DELETE and so on.
🌐
HatchJS
hatchjs.com › home › nestjs swagger authorization header: a guide
NestJS Swagger Authorization Header: A Guide
January 5, 2024 - You learned how to add the `@nestjs/swagger` package to your project, configure the `@nestjs/swagger` module to use the Swagger Authorization Header, and add the `@nestjs/swagger` decorator to your controller methods to protect them with the Swagger Authorization Header.
Find elsewhere
🌐
GitHub
github.com › nestjs › swagger › blob › master › lib › decorators › api-header.decorator.ts
swagger/lib/decorators/api-header.decorator.ts at master · nestjs/swagger
OpenAPI (Swagger) module for Nest framework (node.js) :earth_americas: - swagger/lib/decorators/api-header.decorator.ts at master · nestjs/swagger
Author   nestjs
🌐
NestJS
docs.nestjs.com › openapi › introduction
OpenAPI (Swagger) | NestJS - A progressive Node.js framework
While the application is running, open your browser and navigate to http://localhost:3000/api. You should see the Swagger UI.
🌐
GitHub
github.com › nestjs › swagger › issues › 98
Authorization header not sent via the Swagger UI · Issue #98 · nestjs/swagger
June 11, 2018 - My configuration for the Swagger doc is as follows: const options = new DocumentBuilder() .setTitle('AppName') .setDescription('Customer API') .setVersion('0.1') .addTag('customer.api') .addBearerAuth('Authorization', 'header') .setHost('localhost:3001') .build();
Author   nestjs
🌐
Sevic
sevic.dev › notes › swagger-openapi-docs-nestjs
Documenting REST APIs with OpenAPI specs (NestJS/Swagger) | Željko Šević | Node.js Developer
March 16, 2023 - ApiHeader documents endpoint headers ... expected, like error responses. NestJS' Swagger package provides decorators for specific status codes like ApiBadRequestResponse....
🌐
GitHub
github.com › nestjs › swagger › issues › 113
Add Headers to the reponse · Issue #113 · nestjs/swagger
July 13, 2018 - For example inside ApiResponse we could have an array of headers to add to the documentation. In swagger we can do that, ex: https://swagger.io/docs/specification/describing-responses/
Author   nestjs
🌐
npm
npmjs.com › package › @nestjs › swagger
nestjs/swagger
2 weeks ago - OpenAPI (Swagger) module for Nest. $ npm i --save @nestjs/swagger · Overview & Tutorial · Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please read more here. Author - Kamil Myśliwiec ·
      » npm install @nestjs/swagger
    
Published   Jul 17, 2026
Version   11.4.6
🌐
Medium
rehmat-sayany.medium.com › integrating-swagger-with-nestjs-a-step-by-step-guide-abd532743c43
Integrating Swagger with NestJS: A Step-by-Step Guide | by Rehmat Sayany | Medium
August 11, 2023 - Poulates request body for swagger in the below image ... In some scenarios, you may have parameters that are consistent across all routes, such as headers for authentication. In my case, we have a country parameter which is a query parameter and is required in all routes of the application. NestJS Swagger has a direct way to globally set these.
🌐
Trilon Consulting
trilon.io › blog › nestjs-swagger-tips-tricks
Swagger API Documentation Tips and Tricks - Trilon Consulting
November 10, 2022 - The most used specification for this kind of task, by far, is OpenAPI (maintained by the OpenAPI initiative). If you're using NestJS, there is a wonderful @nestjs/swagger module in the NestJS ecosystem that will help us a lot here!
🌐
GitHub
github.com › nestjs › swagger › issues › 287
API header decorator on controller level · Issue #287 · nestjs/swagger
July 8, 2019 - We have multiple headers that are needed for every call for every controller. The current solution per endpoint has resulted multiple times in documentation errors. Due to the repetitious nature of defining these global headers. Nest version: 6.0.4 @nestjs/swagger version: 3.0.2
Author   nestjs
🌐
DEV Community
dev.to › zsevic › documenting-rest-apis-with-openapi-docs-nestjsswagger-2554
Documenting REST APIs with OpenAPI specs (NestJS/Swagger) - DEV Community
December 16, 2024 - const SWAGGER_API_ENDPOINT = '/api-docs'; // ... export const setupApiDocs = (app: INestApplication): void => { const options = new DocumentBuilder() .setTitle(SWAGGER_API_TITLE) .setDescription(SWAGGER_API_DESCRIPTION) .setVersion(SWAGGER_API_VERSION) .addSecurity('token', { type: 'apiKey', scheme: 'api_key', in: 'header', name: 'auth-token', }) .addBearerAuth() .build(); const document = SwaggerModule.createDocument(app, options); SwaggerModule.setup(SWAGGER_API_ENDPOINT, app, document); }; Configure the plugin in the NestJS config file.
🌐
GitHub
github.com › nestjs › swagger › issues › 2990
Support for Header Versioning · Issue #2990 · nestjs/swagger
June 26, 2024 - The issue described in nestjs/swagger#2235 persists in the latest version. The Swagger module does not support the type of versioning with HEADER that NestJS supports in its core.
Author   nestjs