Swagger自动生成Model类文档的机制及Setter异常问题咨询

问题场景 #

原本以为Swagger会扫描类路径读取类属性，但遇到了不符合预期的情况：

示例类定义 #

public class A {
    public String var1;
    public String var2;

    public String setTestVar1(String var1){
         this.var1 = var1;
      }
}

异常现象 #

在Swagger UI中，该类显示了三个字段：var1、var2、testVar1。虽然修改Setter命名就能解决问题，但想明确Swagger的具体工作机制：它是否会扫描类属性？是否会识别非标准命名的Setter（比如不是setVar2这类符合JavaBean规范的Setter）？

使用的依赖 #

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-jaxrs2</artifactId>
</dependency>

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-jaxrs2-servlet-initializer-v2</artifactId>
</dependency>

核心机制说明 #

你用的是OpenAPI 3.x的swagger-core实现，它生成Model元数据时，会同时扫描类的public属性和符合JavaBean规范的Getter/Setter方法，具体规则如下：

• 直接识别public修饰的类属性：示例里的var1、var2会被直接加入Model定义。
• 解析Setter方法严格遵循JavaBean规范：标准Setter必须是setXxx格式，Xxx对应字段名（首字母大写），解析后会把xxx作为字段名。但如果Setter命名不符合这个规范，比如你写的setTestVar1，Swagger会直接把TestVar1转成小驼峰testVar1，当成一个独立的新字段，完全不会关联到它实际操作的var1属性上。

这就是Swagger UI里多出testVar1的原因——它不会智能关联非标准Setter和已有属性，只会按命名规则识别字段。

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