如何通过自定义服务在Swagger UI中覆盖自定义ID对象的示例生成

你已经通过Jackson处理了UserId的序列化/反序列化，现在要让Swagger UI里的请求体示例将userId显示为字符串而非嵌套对象，且不想用注解，可以通过SpringDoc的自定义扩展组件实现：

方案1：使用SchemaCustomizer自定义类型Schema #

创建一个实现SchemaCustomizer的组件，针对UserId类型修改其OpenAPI Schema定义：

import org.springdoc.core.customizers.SchemaCustomizer;
import org.springframework.stereotype.Component;
import io.swagger.v3.oas.models.media.Schema;

@Component
public class UserIdSchemaCustomizer implements SchemaCustomizer {

    @Override
    public void customize(Schema schema, Class<?> type) {
        // 仅处理UserId类型
        if (type.equals(UserId.class)) {
            // 设置Schema类型为string，格式为uuid
            schema.setType("string");
            schema.setFormat("uuid");
            // 设置示例值
            schema.setExample("e73cd525-f324-4589-9498-006bd21750cd");
            // 清空原有的嵌套属性定义，避免显示嵌套结构
            schema.setProperties(null);
            schema.setAdditionalProperties(false);
        }
    }
}

这个组件会被Spring自动扫描并注册，SpringDoc在生成Schema时会自动调用它修改UserId的定义，最终请求体中的userId字段会显示为字符串示例。

方案2：使用OpenApiCustomiser全局修改Schema #

如果需要更全局的控制，可以实现OpenApiCustomiser，直接修改生成好的OpenAPI文档中的UserId Schema：

import org.springdoc.core.customizers.OpenApiCustomiser;
import org.springframework.stereotype.Component;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.media.Schema;

import java.util.Map;

@Component
public class UserIdOpenApiCustomiser implements OpenApiCustomiser {

    @Override
    public void customise(OpenAPI openApi) {
        Map<String, Schema> schemas = openApi.getComponents().getSchemas();
        if (schemas != null && schemas.containsKey("UserId")) {
            Schema userIdSchema = schemas.get("UserId");
            userIdSchema.setType("string");
            userIdSchema.setFormat("uuid");
            userIdSchema.setExample("e73cd525-f324-4589-9498-006bd21750cd");
            userIdSchema.setProperties(null);
            userIdSchema.setAdditionalProperties(false);
        }
    }
}

说明 #

• 两种方案都不需要在UserId类上添加任何Swagger相关注解，完全通过自定义服务实现。
• 因为你已经处理了Jackson的序列化/反序列化，接口的实际请求响应不会受影响，仅Swagger UI的示例和Schema展示会改为字符串形式。

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