NestJS/Swagger如何修改基础认证默认的Username字段为Email

该需求完全可以实现，整个调整过程不需要修改本地身份校验（LocalAuthGuard）的核心业务逻辑，仅需针对Swagger文档的认证展示规则做适配调整即可。
你之前看到Swagger认证交互区域默认展示username、password两个字段，是因为@ApiBasicAuth()是Nest Swagger封装的内置Basic认证方案，它生成的认证弹窗的字段提示是组件硬编码的，无法直接通过装饰器参数修改，需要替换内置的认证配置才能调整展示文案。

步骤1 移除接口的默认BasicAuth装饰 #

把登录接口上原来的@ApiBasicAuth()代码删掉，避免内置配置和后续自定义配置冲突，修改后的接口基础代码如下：

@UseGuards(LocalAuthGuard)
@Post('login')
async login(@Request() req) {
  return this.authService.login(req.user);
}

步骤2 全局配置自定义Swagger认证方案 #

打开项目中初始化Swagger文档的代码（通常在main.ts的DocumentBuilder配置段），根据你实际的登录传参逻辑选择对应配置：

场景1 保持原有Basic Auth传参逻辑不变 #

如果你的登录逻辑是从请求头的Authorization字段解析Base64编码的账号密码，就替换原来内置的.addBasicAuth()配置为自定义认证方案，同时配合Swagger UI的自定义配置修改弹窗的字段提示文案：

const config = new DocumentBuilder()
  .setTitle('项目API文档')
  .setVersion('1.0')
  // 替换原来的.addBasicAuth()配置
  .addSecurity('basic-auth-custom', {
    type: 'http',
    scheme: 'basic',
    description: '请输入注册邮箱和账号密码完成登录'
  })
  .addSecurityRequirements('basic-auth-custom')
  .build();

// 自定义Swagger UI的弹窗文案，把默认的username提示改成email
const swaggerCustomOptions = {
  swaggerOptions: {
    authAction: {
      'basic-auth-custom': {
        usernameText: 'Email',
        passwordText: 'Password'
      }
    }
  }
};

const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('api-docs', app, document, swaggerCustomOptions);

这种配置下，Swagger弹窗输入的账号密码依然会按照Basic Auth规则拼成Authorization请求头传给后端，和原来的传参逻辑完全一致，不需要调整后端接口的参数提取逻辑。

场景2 适配POST请求体传参的登录逻辑 #

如果你的登录逻辑是从POST请求体中提取email和password参数，而非从Authorization头解析，就不需要使用内置的BasicAuth弹窗，直接定义接口对应的请求体DTO即可，Swagger会自动生成对应字段的输入框：

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

// 定义登录请求DTO
class LoginDto {
  @ApiProperty({ description: '注册邮箱' })
  email: string;

  @ApiProperty({ description: '账号密码' })
  password: string;
}

// 接口方法注入请求体参数
@UseGuards(LocalAuthGuard)
@Post('login')
async login(@Body() loginDto: LoginDto) {
  return this.authService.login(loginDto);
}

步骤3 给登录接口绑定自定义认证方案 #

在登录接口上，使用@ApiSecurity装饰器绑定刚才定义的自定义认证方案，替换原来的@ApiBasicAuth()：

@ApiSecurity('basic-auth-custom')
@UseGuards(LocalAuthGuard)
@Post('login')
async login(@Request() req) {
  return this.authService.login(req.user);
}

• 自定义配置完成后，无需修改LocalAuthGuard、LocalAuthStrategy的核心逻辑，只要保证LocalAuthStrategy中的usernameField配置为email，身份校验流程就可以正常运行。
• 绑定自定义认证方案时，一定要保证@ApiSecurity的参数值和全局配置中addSecurity定义的方案名称完全一致，否则Swagger不会在接口上展示对应的认证交互区域。

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