Order of parameters not respected

[ivansenic]

The order of parameters defined in the @Parameters is no respected.. This results in a crazy order, especially in a Swagger UI and is very confusing for a user imo.

For example, having the:

  @Parameters(
      value = {
        @Parameter(name = "namespace", ref = OpenApiConstants.Parameters.NAMESPACE),
        @Parameter(name = "collection", ref = OpenApiConstants.Parameters.COLLECTION),
        @Parameter(name = "where", ref = OpenApiConstants.Parameters.WHERE),
        @Parameter(name = "fields", ref = OpenApiConstants.Parameters.FIELDS),
        @Parameter(
            name = "page-size",
            in = ParameterIn.QUERY,
            description = "The max number of results to return.",
            schema =
                @Schema(
                    implementation = Integer.class,
                    defaultValue = "3",
                    minimum = "1",
                    maximum = "20")),
        @Parameter(name = "page-state", ref = OpenApiConstants.Parameters.PAGE_STATE),
        @Parameter(name = "profile", ref = OpenApiConstants.Parameters.PROFILE),
        @Parameter(name = "raw", ref = OpenApiConstants.Parameters.RAW),
      })

will result in the following order in the openapi.json

      parameters:
      - name: page-size
        in: query
        description: The max number of results to return.
        schema:
          format: int32
          default: "100"
          minimum: 1
          type: integer
      - $ref: '#/components/parameters/collection'
      - $ref: '#/components/parameters/document-id'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/page-state'
      - $ref: '#/components/parameters/profile'
      - $ref: '#/components/parameters/raw'
      - $ref: '#/components/parameters/where'

and eventually looking like this in Swagger UI: