Spring Boot Swagger如何为同类型属性添加独立描述

问题原因 #

当属性类型为自定义类时，Swagger默认会生成$ref引用该类的全局Schema，导致属性自身的@Schema描述被覆盖，所有同类型属性共用类的描述。而String、Double等基础类型不会生成ref，因此描述能正常生效。

解决方案 #

方案1：内联Schema（避免$ref） #

在属性的@Schema注解中指定implementation为目标类，同时保留描述。Swagger会将类的结构内联到属性下，而非使用ref，从而保留属性的独立描述：

@Schema(description = "elm1 description", implementation = Element.class)
Element elm1;

@Schema(description = "elm2 description", implementation = Element.class)
Element elm2;

@Schema(description = "Element description")
public class Element {
    public Element() { }
    // 类的其他字段...
}

该方式会重复生成Element的结构，适合类结构简单的场景。

方案2：为每个属性创建独立Schema别名 #

给每个属性的@Schema指定不同的name，让Swagger生成多个结构一致但描述不同的独立Schema，属性的ref会指向对应的别名Schema：

@Schema(name = "Elm1Element", description = "elm1 description")
Element elm1;

@Schema(name = "Elm2Element", description = "elm2 description")
Element elm2;

@Schema(description = "Element description")
public class Element {
    public Element() { }
    // 类的其他字段...
}

此时Swagger的components中会生成Elm1Element和Elm2Element两个Schema，各自带有独立描述。

方案3：自定义ModelBuilder插件（适用于SpringDoc） #

如果使用SpringDoc（主流Swagger替代实现），可以通过自定义插件强制覆盖属性描述，即使使用ref也能保留独立描述：

@Component
public class CustomModelBuilderPlugin implements ModelBuilderPlugin {
    @Override
    public void apply(ModelContext modelContext) {
        modelContext.getProperties().forEach((propName, propContext) -> {
            if (propContext.getAnnotatedElement() != null) {
                Schema schemaAnn = propContext.getAnnotatedElement().getAnnotation(Schema.class);
                if (schemaAnn != null && StringUtils.isNotBlank(schemaAnn.description())) {
                    propContext.getBuilder().description(schemaAnn.description());
                }
            }
        });
    }

    @Override
    public boolean supports(DocumentationType documentationType) {
        return DocumentationType.OAS_30.equals(documentationType);
    }
}

该插件会遍历属性，将属性上的@Schema描述覆盖到对应的Model属性中。

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