如何让SpringDoc生成的OpenAPIv3文档匹配HAL格式链接？

方案一：全局替换链接字段名（推荐） #

创建自定义ModelConverter插件，让SpringDoc在生成OpenAPI模型时自动将links替换为_links：

import io.swagger.v3.core.converter.ModelConverterContext;
import io.swagger.v3.core.converter.ModelConverterPlugin;
import io.swagger.v3.core.converter.ResolvedSchema;
import io.swagger.v3.oas.models.media.Schema;
import org.springframework.stereotype.Component;

import java.util.Iterator;
import java.util.Map;

@Component
public class HalLinksModelConverter implements ModelConverterPlugin {

    @Override
    public boolean supports(Class<?> type) {
        // 匹配所有继承自RepresentationModel的资源类
        return org.springframework.hateoas.RepresentationModel.class.isAssignableFrom(type);
    }

    @Override
    public ResolvedSchema resolve(Class<?> type, ModelConverterContext context, Iterator<ModelConverterPlugin> chain) {
        ResolvedSchema resolvedSchema = chain.next().resolve(type, context, chain);
        Schema<?> schema = resolvedSchema.schema;

        if (schema != null && schema.getProperties() != null) {
            Map<String, Schema<?>> properties = schema.getProperties();
            // 替换字段名并同步required列表
            if (properties.containsKey("links")) {
                Schema<?> linksSchema = properties.remove("links");
                properties.put("_links", linksSchema);
                
                if (schema.getRequired() != null) {
                    schema.getRequired().remove("links");
                    schema.getRequired().add("_links");
                }
            }
        }

        return resolvedSchema;
    }
}

这个类会被Spring自动扫描并注册到SpringDoc的模型转换流程中，全局修正所有HATEOAS资源类的链接字段名。

方案二：单个资源类指定字段名 #

如果只有少数几个资源类，可以直接在资源类中重写getLinks()方法并通过@Schema注解指定字段名：

import org.springframework.hateoas.RepresentationModel;
import io.swagger.v3.oas.annotations.media.Schema;

public class UserResource extends RepresentationModel<UserResource> {
    // 业务字段定义...

    @Override
    @Schema(name = "_links")
    public Links getLinks() {
        return super.getLinks();
    }
}

额外注意事项 #

• 确保使用最新稳定版的springdoc-openapi-starter-webmvc-ui（或对应环境的starter），避免旧版本兼容性问题。
• 无需依赖spring-data-rest，上述方案仅依赖Spring HATEOAS和SpringDoc核心组件。

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