如何使Swagger展示JsonNode属性的@Schema注解描述？

方案1：补充@Schema的类型指定 #

JsonNode属于动态结构，Swagger默认对其注解解析支持有限，可通过显式指定type和implementation属性，让Swagger正确识别字段的描述信息：

import com.fasterxml.jackson.databind.JsonNode;
import io.swagger.v3.oas.annotations.media.Schema;

public class UserRequest {
     @Schema(name = "name", description = "Username", example = "Rafael")
     private String name;

     @Schema(
         name = "params", 
         description = "Parameters XPTO",
         type = "object",
         implementation = JsonNode.class
     )
     private JsonNode params;
}

方案2：API方法层面显式定义请求体结构 #

在Controller的API方法中，通过@Content配合@RequestBody，强制Swagger解析请求体类的完整注解信息：

@PostMapping("/users")
@Operation(summary = "创建用户")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "成功创建用户")
})
public ResponseEntity<UserResponse> createUser(
    @RequestBody 
    @Content(mediaType = MediaType.APPLICATION_JSON_VALUE,
             schema = @Schema(implementation = UserRequest.class))
    UserRequest request
) {
    // 业务逻辑实现
}

方案3：自定义JsonNode模型转换器 #

如果上述方案无效，可以编写自定义的ModelConverter，让Swagger对JsonNode类型做特殊处理，确保读取@Schema的描述：

import com.fasterxml.jackson.databind.JsonNode;
import io.swagger.v3.core.converter.ModelConverter;
import io.swagger.v3.core.converter.ModelConverterContext;
import io.swagger.v3.core.converter.ModelConverterImpl;
import io.swagger.v3.oas.models.media.Schema;
import org.springframework.stereotype.Component;

import java.lang.reflect.Type;
import java.util.Iterator;

@Component
public class JsonNodeModelConverter extends ModelConverterImpl {
    @Override
    public Schema resolve(Type type, ModelConverterContext context, Iterator<ModelConverter> chain) {
        if (type instanceof Class && JsonNode.class.isAssignableFrom((Class<?>) type)) {
            Schema schema = super.resolve(type, context, chain);
            // 可通过反射读取字段上的@Schema注解，将描述等信息设置到schema中
            return schema;
        }
        return chain.hasNext() ? chain.next().resolve(type, context, chain) : null;
    }
}

确保该转换器被Spring容器扫描到，或者手动注册到Swagger配置类中。

方案4：升级Swagger依赖版本 #

部分旧版本的Swagger（如springdoc-openapi v1.x系列）存在JsonNode注解解析的bug，升级到最新稳定版（如v2.x+）可直接解决问题。

Maven依赖示例：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>

Gradle依赖示例：

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

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