如何在NestJS的SwaggerUI中集成Keycloak实现认证按钮功能

要让SwaggerUI支持Keycloak用户名密码认证并自动获取JWT令牌访问受保护接口，只需修改Swagger的配置逻辑，添加OAuth2认证支持，具体步骤如下：

1. 更新Swagger文档配置，添加Keycloak OAuth2认证规则 #

替换你现有的Swagger DocumentBuilder 代码，新增OAuth2安全方案，指定Keycloak的令牌获取地址、认证流程等信息：

const config = new DocumentBuilder()
  .setTitle('<Title>')
  .setDescription('Example Description')
  .setVersion('1.0')
  // 配置Keycloak OAuth2密码模式认证
  .addSecurity('oauth2', {
    type: 'oauth2',
    flows: {
      password: {
        tokenUrl: `${process.env.KEYCLOAK_AUTH_SERVER_URL}/realms/${process.env.KEYCLOAK_REALM}/protocol/openid-connect/token`,
        scopes: {} // 若接口需要特定权限范围，可在此添加，比如 { "api-access": "访问API接口" }
      }
    }
  })
  .build();

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

2. 为受保护接口添加认证标记 #

在需要Keycloak保护的控制器或单个接口方法上，添加@ApiSecurity('oauth2')装饰器，Swagger会自动识别该接口需要认证才能访问：

import { ApiSecurity } from '@nestjs/swagger';

@Controller('protected')
@ApiSecurity('oauth2') // 标记整个控制器下的接口都需要认证
export class ProtectedController {
  @Get()
  getProtectedData() {
    return { message: '这是受保护的接口数据' };
  }
}

3. 优化SwaggerUI认证体验（可选） #

在SwaggerModule.setup时添加额外配置，预填充Keycloak客户端ID、Realm等信息，避免每次认证重复输入：

SwaggerModule.setup('api', app, document, {
  swaggerOptions: {
    oauth2RedirectUrl: `${process.env.APP_URL}/api/oauth2-redirect`, // 需与Keycloak客户端配置的"有效重定向URI"一致
    oauth: {
      clientId: process.env.KEYCLOAK_CLIENT_ID,
      realm: process.env.KEYCLOAK_REALM,
      appName: '<Title>',
      scopeSeparator: ' '
    }
  }
});

验证效果 #

启动项目后访问SwaggerUI（默认路径/api），右上角会出现Authorize按钮，点击后输入Keycloak的用户名和密码，完成授权后，Swagger会自动携带JWT令牌访问所有标记了@ApiSecurity('oauth2')的接口。

内容的提问来源于stack exchange，提问作者Patler