SpringDoc项目中属性名以"set"开头引发的OpenAPI文档生成问题解析

问题现象

在使用SpringDoc生成OpenAPI文档时，开发人员发现当DTO类中存在以"set"开头的属性名时，会自动生成一个错误的额外属性。例如，当类中存在名为"setting"的属性时，OpenAPI文档中会意外出现一个名为"ting"的冗余属性引用。

问题根源

这个问题本质上源于Swagger核心库对Java类方法的自省机制。Swagger在生成API文档时，不仅会解析@Schema注解，还会分析类的公共方法签名来推断可能的属性。

具体来说，Swagger会按照以下规则处理：

1. 对于以"get"、"set"或"is"开头的方法，会移除这些前缀来推导属性名
2. 对于其他方法，如果方法名恰好以"set"开头，也会被错误地识别为setter方法

因此，当存在名为"setting"的属性时：

• 正确的setter方法setSetting会被识别为"setting"属性
• 但builder风格的setting()方法也会被误认为setter，移除"set"前缀后就变成了"ting"

解决方案

推荐方案：遵循JavaBean命名规范

最彻底的解决方案是严格遵循JavaBean规范：

1. 属性访问方法统一使用get/set前缀
2. 避免使用builder风格的方法名（如setting()）
3. 对于布尔类型属性，使用is前缀

修改后的代码示例：

// 使用标准getter/setter
public String getSetting() {
    return setting;
}

public void setSetting(String setting) {
    this.setting = setting;
}

// 避免使用builder风格的方法名
public SampleResponse withSetting(String setting) {
    this.setting = setting;
    return this;
}

临时解决方案：使用@Schema注解

如果暂时无法修改方法命名，可以使用@Schema(hidden = true)注解标记不应出现在API文档中的方法：

@Schema(hidden = true)
public SampleResponse setting(String setting) {
    this.setting = setting;
    return this;
}

深入理解

这个问题揭示了API文档生成工具的一个重要特性：它们不仅依赖显式声明的注解，还会通过代码分析来推断接口结构。这种设计虽然提高了便利性，但也可能带来意外的结果。

在实际开发中，建议：

1. 保持DTO类的简洁性，仅包含与API交互相关的属性
2. 避免在DTO类中混入构建器模式等复杂逻辑
3. 定期检查生成的OpenAPI文档是否符合预期

最佳实践

对于使用SpringDoc的项目，建议建立以下规范：

1. DTO类专门用于API交互，与业务逻辑分离
2. 使用Lombok的@Data或@Getter/@Setter减少样板代码
3. 复杂的对象构建逻辑放在单独的Builder类中
4. 在CI流程中加入OpenAPI文档的校验步骤

通过遵循这些规范，可以避免文档生成时的意外行为，同时提高代码的可维护性。