Quarkus中通过自定义OASFilter修改SmallRye MicroProfile Schema引用值失败

现有代码的问题点 #

1. 字符串比较错误：Java中字符串内容比较要使用equals()，而非==——==比较的是对象引用地址，不是字符串内容。
2. Ref格式错误：OpenAPI组件引用的标准格式是#/components/schemas/[schemaName]，你写的#components/schemas/microProfile缺少了开头的/，不符合规范。
3. 未注册自定义Schema：仅修改API响应的引用指向，但没有在OpenAPI的components中添加microProfile这个自定义Schema，导致引用无法找到对应实体。

完整解决方案 #

要实现你的需求，需在自定义过滤器中完成两个核心操作：注册自定义microProfile Schema到OpenAPI组件，同时修正API响应引用的代码错误。

自定义过滤器完整代码

import org.eclipse.microprofile.openapi.OASFilter;
import org.eclipse.microprofile.openapi.models.Components;
import org.eclipse.microprofile.openapi.models.OpenAPI;
import org.eclipse.microprofile.openapi.models.responses.APIResponse;
import org.eclipse.microprofile.openapi.models.media.Schema;
import java.util.HashMap;
import java.util.Map;

public class CustomHealthOASFilter implements OASFilter {

    @Override
    public APIResponse filterAPIResponse(APIResponse apiResponse) {
        // 修正字符串比较逻辑与ref格式
        if ("#/components/schemas/HealthCheckResponse".equals(apiResponse.getRef())) {
            apiResponse.setRef("#/components/schemas/microProfile");
        }
        return apiResponse;
    }

    @Override
    public void filterOpenAPI(OpenAPI openAPI) {
        Components components = openAPI.getComponents();
        if (components == null) {
            components = openAPI.schemaBuilder().components().build();
            openAPI.setComponents(components);
        }

        // 构建自定义的microProfile Schema
        Schema<Object> microProfileSchema = openAPI.schemaBuilder()
                .type(Schema.SchemaType.OBJECT)
                .description("microprofile response")
                .addProperty("data", openAPI.schemaBuilder()
                        .type(Schema.SchemaType.OBJECT)
                        .description("Information of the service. If the service is down, this holds the information of why it is failed.")
                        .build())
                .addProperty("name", openAPI.schemaBuilder()
                        .type(Schema.SchemaType.STRING)
                        .description("Service Name ")
                        .build())
                .addProperty("status", openAPI.schemaBuilder()
                        .type(Schema.SchemaType.STRING)
                        .description("Service Status ")
                        .build())
                .build();

        // 将自定义Schema注册到components中
        Map<String, Schema> schemas = components.getSchemas();
        if (schemas == null) {
            schemas = new HashMap<>();
            components.setSchemas(schemas);
        }
        schemas.put("microProfile", microProfileSchema);
        // 可选：移除原有的健康检查相关Schema
        schemas.remove("HealthCheckResponse");
        schemas.remove("HealthCheckStatus");
    }
}

替代方案：直接修改原有Schema属性描述 #

如果不需要替换Schema名称，仅需给原有属性添加描述，可简化代码直接修改HealthCheckResponse：

@Override
public void filterOpenAPI(OpenAPI openAPI) {
    Components components = openAPI.getComponents();
    if (components == null) return;

    Schema healthCheckSchema = components.getSchemas().get("HealthCheckResponse");
    if (healthCheckSchema != null) {
        // 给data属性添加描述
        healthCheckSchema.getProperties().get("data").setDescription("Information of the service. If the service is down, this holds the information of why it is failed.");
        // 给name属性添加描述
        healthCheckSchema.getProperties().get("name").setDescription("Service Name ");
        // 替换status属性并添加描述
        Schema statusSchema = openAPI.schemaBuilder()
                .type(Schema.SchemaType.STRING)
                .description("Service Status ")
                .enumItems("UP", "DOWN")
                .build();
        healthCheckSchema.getProperties().put("status", statusSchema);
    }
}

配置验证 #

确保application.properties中的过滤器配置路径正确：

mp.openapi.filter=com.yourpackage.CustomHealthOASFilter

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