从 Swagger/OpenAPI 定义生成的方法中参数的顺序

问：

一点背景。在我的系统中，ServiceB 调用 ServiceA。ServiceA 提供了一个 Swagger/OpenAPI 定义，ServiceB 使用该定义来生成其客户端代码。

ServiceA 需要一些自定义标头参数，这些参数通过 addOperationCustomizer 方法添加到 GroupedOpenAPI。

@Bean
public GroupedOpenApi opeApiDefinitionBuilder() {
    return GroupedOpenApi.builder()
        .addOperationCustomizer(zzzHeaderParameterAdder)
        .addOperationCustomizer(yyyHeaderParameterAdder)
        .addOperationCustomizer(xxxHeaderParameterAdder)
        .build();
        }
 
// where xxxHeaderParameterAdder and others are an instance of

@Component
public class YYYHeaderParameterAdder implements OperationCustomizer {

  @Override
  public Operation customize(Operation operation, HandlerMethod handlerMethod) {

    Parameter extraParam = new Parameter()
        .in(ParameterIn.HEADER.toString())
        .name("parameterXXX")
        .schema(new Schema().type("string"))
        .required(Boolean.TRUE);

    operation.addParametersItem(extraParam);

    return operation;
  }
}

当使用带有 springdoc-openapi-ui 的 Spring Boot 2 时，流派化的 swagger 定义包含按操作注册的 revers 顺序添加的已定义参数（查询来自 endpoind 定义）。

        "parameters" : [
          {
            "name" : "id",
            "in" : "query",
            "required" : true,
            "schema" : {
              "type" : "string"
            },
          },
          {
            "name" : "parameterXXX",
            "in" : "header",
            "required" : true,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "parameterYYY",
            "in" : "header",
            "required" : true,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "parameterZZZ",
            "in" : "header",
            "required" : false,
            "schema" : {
              "type" : "string"
            }
          }

因此，gernerated 客户端代码如下所示：

getWhatever(String id, String parameterXXX, String parameterYYY, String parameterZZZ) { body here}

升级到 Spring Boot 3 并切换到 springdoc-openapi-starter-webmvc-ui 后，参数顺序颠倒了

        "parameters" : [
          {
            "name" : "id",
            "in" : "query",
            "required" : true,
            "schema" : {
              "type" : "string"
            },
          },
          {
            "name" : "parameterZZZ",
            "in" : "header",
            "required" : false,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "parameterYYY",
            "in" : "header",
            "required" : true,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "parameterXXX",
            "in" : "header",
            "required" : true,
            "schema" : {
              "type" : "string"
            }
          }

导致不同客户端代码的原因

getWhatever(String id, String parameterZZZ, String parameterYYY, String parameterXXX) { body here}

总结一下

// new client generated code
getWhatever(String id, String parameterZZZ, String parameterYYY, String parameterXXX) { body here}
// old client generated code
getWhatever(String id, String parameterXXX, String parameterYYY, String parameterZZZ) { body here}

编译器无法检测到此错误，因为所有参数都是字符串。

io.swagger.v3.oas.models.Operation 类没有允许操作顺序的属性。如何处理这个问题？