Maven plugin should be configurable regarding the order of the parameters in a REST endpoint

[cristalp]

We use Swagger annotations and a different Maven plugin to generate OpenAPI from our Java code. But we want to migrate to Eclipse MicroProfile annotations and the Smallrye toolchain.

There is a difference in the generated OpenAPI regarding the order of the parameters in a REST endpoint.

For instance:

  public Response endpoint(
      @Parameter(description = "The foo") @PathParam("foo") final String foo,
      @Parameter(description = "The bar") @PathParam("bar") final String bar) {
    return null;
  }

• The Swagger toolchain lists parameters as they are defined in the Java code. So OpenAPI first contains foo and then bar.
• The Smallrye toolchain lists parameters alphabetically. So OpenAPI first contains bar and then foo.

While this could be called nitpicking, I do believe that the order of the parameters is important. Main parameters (like an ID) should come first and optional parameters should come later.

In order not to break existing behavior, the Maven plugin should contain a flag defining how parameters are sorted. For instance orderParametersAlphabetically which defaults to true. If it's false, the order is defined by their order in the Java code.

[MikeEdgar]

This is a reasonable request. We currently support it when @Parameter is on the method rather than the arguments, but that results in duplication because the name at least is needed on the @Parameter to link it to the correct argument.