Spring Fox Swagger UI密码未掩码问题求助

我之前在使用Spring Fox Swagger UI时也碰到过密码输入框不掩码的问题，结合你给出的代码片段，给你几个可行的排查和解决思路：

• 检查Spring Fox版本兼容性
  如果你使用的是Spring Fox 2.x系列（比如2.9.x及以下），旧版本对@ApiParam的format="password"支持可能存在局限性。建议确认你的Spring Fox版本，若版本较低，可以尝试升级到3.x版本（注意3.x开始使用OpenAPI规范，注解体系有变化），或者针对旧版本做额外配置。

• 替换为OpenAPI规范的注解（适用于Spring Fox 3.x+）
  Spring Fox 3.x之后推荐使用OpenAPI的原生注解替代旧的@ApiParam。你可以把参数上的@ApiParam替换为@Parameter结合@Schema来定义密码类型：

  import io.swagger.v3.oas.annotations.Parameter;
  import io.swagger.v3.oas.annotations.media.Schema;
  
  public ResponseEntity<?> createJiraIssue(
          @RequestParam(value = "jiraProject") 
          @ApiParam(value = ParamConfig.PROJECT_DESC) String jiraProject, 
          @RequestParam(value = "qcPassword", required = false) 
          @Parameter(schema = @Schema(type = "string", format = "password")) 
          @ApiParam(value = ParamConfig.QC_PASSWORD) String qcPassword 
  ) throws CustomException, IOException, URISyntaxException
  

  这种方式更贴合OpenAPI规范，Swagger UI对它的支持更稳定。

• 在Swagger配置中手动指定参数类型
  如果升级注解或版本暂时不可行，可以在Docket配置中手动修改该参数的类型，强制Swagger UI渲染为密码输入框：

  @Bean
  public Docket api() {
      return new Docket(DocumentationType.SWAGGER_2)
              .select()
              .apis(RequestHandlerSelectors.basePackage("your.package.path"))
              .paths(PathSelectors.any())
              .build()
              .operations(operation -> {
                  // 找到目标操作并修改参数
                  if ("createJiraIssue".equals(operation.getOperationId())) {
                      operation.getParameters().forEach(param -> {
                          if ("qcPassword".equals(param.getName())) {
                              param.setModelRef(new ModelRef("string"));
                              param.setFormat("password");
                          }
                      });
                  }
                  return operation;
              });
  }
  

  这段代码会针对createJiraIssue接口的qcPassword参数，强制设置其格式为password，触发UI的掩码效果。

• 考虑将参数封装到RequestBody（业务允许的话）
  如果你业务上允许，把请求参数封装成一个DTO类，使用@RequestBody接收，然后在DTO的密码字段上使用@ApiModelProperty标注密码类型，这种方式Swagger UI的支持通常更可靠：

  // DTO类
  public class JiraIssueRequest {
      @ApiParam(value = ParamConfig.PROJECT_DESC)
      private String jiraProject;
      
      @ApiModelProperty(type = "string", format = "password", value = ParamConfig.QC_PASSWORD)
      private String qcPassword;
      
      // getter和setter方法
  }
  
  // 修改后的接口
  public ResponseEntity<?> createJiraIssue(@RequestBody JiraIssueRequest request) 
          throws CustomException, IOException, URISyntaxException
  

  这种方式下，Swagger UI会自动把密码字段渲染为掩码输入框。

• 检查Swagger UI与Spring Fox的版本匹配
  确保你的Swagger UI依赖版本和Spring Fox版本是匹配的：比如Spring Fox 2.x对应Swagger UI 2.x，Spring Fox 3.x对应Swagger UI 3.x。版本不匹配可能导致UI无法正确识别密码格式配置。

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