Define parameter processing behavior

[MikeEdgar]

The three attributes that uniquely identify a parameter are name, in, and style (to differentiate between basic path and matrix parameters). In cases where an application uses annotations to document an API and the annotations conflict, it would be helpful to have consistent, defined behavior.

Consider the following example from the Pet Store API in the TCK. The use of different names for the same header parameter seems to indicate that an OAI annotation "overrides" the name that JAX-RS will use at run time. That may make sense for applications that want to expose an API that passes through some front-end translation layer, but generally it exposes incorrect information and it is currently enforced by the TCK.

microprofile-open-api/tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/PetResource.java

Lines 223 to 228 in ac854fe

	@Parameter(
	name = "apiKey",
	description = "authentication key to access this method",
	schema = @Schema(type = SchemaType.STRING, implementation = String.class,
	maxLength = 256, minLength = 32))
	@HeaderParam("api_key") String apiKey,

Suggestions to clarify behavior:

1. If @Parameter and a JAX-RS parameter annotation are both unambiguously specified on the same method parameter or bean property, the @Parameter's name and in attributes are optional and must not conflict with the JAX-RS parameter's inherent values. If @Parameter specifies a ref, the information typically derived from the JAX-RS annotation should be suppressed.
2. matrix style parameters must always specify a value for style, whereas other styles may use the default already defined in the JavaDocs. Remove verbiage that style is "Ignored if the properties content or array are specified."

   microprofile-open-api/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/Parameter.java

   Lines 109 to 119 in ac854fe

   	/**
   	* Describes how the parameter value will be serialized depending on the type of the parameter value.
   	* <p>
   	* Default values (based on value of in):
   	* for query - form; for path - simple; for header - simple; for cookie - form.
   	* </p>
   	* Ignored if the properties content or array are specified.
   	*
   	* @return the style of this parameter
   	**/
   	ParameterStyle style() default ParameterStyle.DEFAULT;

3. When the @Parameter and JAX-RS parameter are specified separately (e.g. on the resource method and on the resource method argument), the name, in, and style attributes must align - otherwise the behavior is "undefined". Using a ref in this case might be discouraged to avoid unexpected behavior, particularly in the cases where a ref refers to an external document or a parameter defined in another phase of generation (i.e. the filter).
4. Due to the fact that JAX-RS does not provide a way to specify a matrix parameter reference in @Path similar to a @PathParam, matrix parameters found in the scan should generate a reference in the path string using the name of the path segment to which the matrix applies, or some other (predictable) uniquely generated name if the matrix applies to a @PathParam. In the following example, the path for the getPerson operation could be something like "api/people{people_matrix}/{person_id}{person_id_matrix}". Each of the "matrix" path variables would be included as separate matrix-style entries in the parameters for the path (people_matrix) or the get method, (person_id_matrix).

@Path("api/people")
public class PeopleResource {
    @MatrixParam("job_title") String jobTitle;

    @Path("{person_id}")
    @GET
    public Response getPerson(
        @PathParam("person_id") String personId,
        @MatrixParam("ageFrom") int ageFrom,
        @MatrixParam("ageTo") int ageTo) {
        ...
    }
}

There may be other things to clarify, but this is what I've run into lately that could benefit from additional clarity in the spec.