是否可以添加身份验证以访问 NestJS 的 Swagger Explorer

Question

我目前在 NestJS 项目中使用 Swagger，并且启用了资源管理器：

在 main.js

const options = new DocumentBuilder()
    .setTitle('My App')
    .setSchemes('https')
    .setDescription('My App API documentation')
    .setVersion('1.0')
    .build()

const document = SwaggerModule.createDocument(app, options)
SwaggerModule.setup('docs', app, document, {
    customSiteTitle: 'My App documentation',
})

有了这个，资源管理器可以访问，/docs这是我所期望的。但我想知道是否可以向资源管理器添加任何身份验证层，因此只接受某些请求。

我想让这个资源管理器在生产中可以访问，但仅限于经过身份验证的用户。

提前致谢 ：）

Answer 1

更新

根据最近DocumentBuilder方法的变化，这对我有用。分享给正在使用新版本的人。

const options = new DocumentBuilder()
.setTitle('My API')
.setDescription('API used for testing purpose')
.setVersion('1.0.0')
.setBasePath('api')
.addBearerAuth(
  { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
  'access-token',
)
.build();

const document = SwaggerModule.createDocument(app, options);

更新另外，请@ApiBearerAuth()在您的控制器功能上使用添加身份验证。

@Get('/test')
@ApiBearerAuth()

access-token是 swagger 文档中供参考的名称。您在标头中的令牌将按如下方式传递：

curl -X GET "http://localhost:3004/test" -H "accept: application/json" -H "Authorization: Bearer test-token"

Answer 2

只需将.addBearerAuth()（不带任何参数）添加到您的 swagger 选项中

和@ApiBearerAuth()你的控制器方法

const options = new DocumentBuilder()
    .setTitle('My App')
    .setSchemes('https')
    .setDescription('My App API documentation')
    .setVersion('1.0')
    .addBearerAuth()
    .build()

Answer 3

这是针对 APIKEY 而非持有者

如果有人到达此帖子并寻找apiKey（而不是持有者），您需要遵循此操作

在 main.ts 中

    const options = new DocumentBuilder()
        .setTitle('CMOR')
        .setDescription('CMOR API documentation')
        .setVersion('1.0')
        .addServer('/api')
        .addApiKey({
            type: 'apiKey', // this should be apiKey
            name: 'api-key', // this is the name of the key you expect in header
            in: 'header',
        }, 'access-key' // this is the name to show and used in swagger
        ) 
        .build();

然后在你的控制器或方法中

@ApiTags('analyzer')
@ApiSecurity('access-key') // this is the name you set in Document builder
@Controller('analyzer')
export class ScreenAnalyzerController {

Answer 4

在@nestjs/swagger 4.0 版中更新了重大/API 更改。

嗨，花了很多尝试和失败才能做到这一点。代码中的注释对于理解很重要。这些名称相互依赖才能发挥作用。

主文件

    const options = new DocumentBuilder()
        .setTitle('my-title')
        .setDescription('my-descirption')
        .setVersion('1.0')
        .addBearerAuth(
          {
            type: 'http',
            scheme: 'bearer',
            bearerFormat: 'JWT',
            name: 'JWT',
            description: 'Enter JWT token',
            in: 'header',
          },
          'JWT-auth', // This name here is important for matching up with @ApiBearerAuth() in your controller!
        )
        .build();
      const document = SwaggerModule.createDocument(app, options);
      SwaggerModule.setup('api', app, document);

在您的控制器中，您执行以下操作（注意 @ApiBearerAuth() 使用与 main.ts 中 swagger 选项上的名称相同的名称）：

app.controller.ts

    @Roles(Role.Admin)
      @UseGuards(JwtAuthGuard, RolesGuard)
      @ApiTags('Admin')
      @ApiOperation({ summary: 'Get admin section' })
      @Get('admin')
      @ApiBearerAuth('JWT-auth') // This is the one that needs to match the name in main.ts
      getAdminArea(@Request() req) {
        return req.user;
      }

希望这可以节省我花时间了解发生了什么的人。

Answer 5

使用带有 Express 的 NestJS 通过 HTTP Basic Auth 保护对 Swagger 的访问

首先运行，npm i express-basic-auth然后将以下内容添加到您的main.{ts,js}：

// add import
import * as basicAuth from 'express-basic-auth';

// ...

// Sometime after NestFactory add this to add HTTP Basic Auth
app.use(
    ['/docs', '/docs-json'],
    basicAuth({
        challenge: true,
        users: {
            yourUserName: 'p4ssw0rd',
        },
    }),
);


// Your code
const options = new DocumentBuilder()
    .setTitle('My App')
    .setSchemes('https')
    .setDescription('My App API documentation')
    .setVersion('1.0')
    .build()

const document = SwaggerModule.createDocument(app, options)
SwaggerModule.setup('docs', app, document, {
    customSiteTitle: 'My App documentation',
})

// ...

有了这个，你将在任何/docs路由上得到一个 HTTP 基本身份验证提示。我们也必须/docs-json明确命名，以保护生成的 JSON OpenAPI 文件。

您不应该将凭据放在您的代码/存储库中，而应该放在您的.env和 通过ConfigService访问。

我首先在这里看到了这个解决方案。

Answer 6

下面的例子运行得很好

.addBearerAuth({ in: 'header', type: 'http' })

in您应该告诉道具中令牌的位置在哪里

由于您覆盖了默认选项，因此您应该传递type

  const options = new DocumentBuilder()
    .setTitle('Api docs for mobile')
    .setDescription('The api docs for the mobile application')
    .setVersion('1.0')
    .addBearerAuth({ in: 'header', type: 'http' })
    .build();

实施addBearerAuth​

  const options = new DocumentBuilder()
    .setTitle('Api docs for mobile')
    .setDescription('The api docs for the mobile application')
    .setVersion('1.0')
    .addBearerAuth({ in: 'header', type: 'http' })
    .build();

Answer 7

添加.addBearerAuth()到您的招摇选项后，您应该添加@ApiBearerAuth()到您的控制器或其方法。

注意：为了在刷新页面后将令牌保留在浏览器中的 swagger UI 中，您应该在 swagger 选项中进行设置：

SwaggerModule.setup('docs', app, document, {
    swaggerOptions: {
        persistAuthorization: true, // this
    },
});