Clean up the Pet Store (and possibly Airlines) app annotations

[EricWittmann]

The Pet Store app (possibly also the Airlines app, I haven't checked) has a number of @Parameter annotations that are likely incorrect because the app was taken from the old Swagger 2.0 codebase. For example, there are a number of @Parameter annotations on method arguments which would typically be represented as a request body. In Swagger 2.0 that was correct, because request bodies were defined as "body" style parameters. In 3.0, however, there is an actual request body. There may be other annotations that do not make sense in 3.0 - so we should review the code.

[arthurdm]

thanks for opening this Eric.

fyi, these were other warnings that we saw from the Pet Store app:

 - Message: Required "scopes" field is missing or is set to an invalid value, Location: #/components/securitySchemes/petsOAuth2/flows/implicit
 - Message: Required "description" field is missing or is set to an invalid value, Location: #/paths/~1pet~1{petId}/get/responses/200
 - Message: Required "in" field is missing or is set to an invalid value, Location: #/paths/~1pet~1{petId}/post/parameters
 - Message: Required "in" field is missing or is set to an invalid value, Location: #/paths/~1pet~1{petId}/post/parameters
 - Message: The "http://example.org/petapi-examples/openapi.json#/components/examples/pet-example" value is an invalid reference, Location: #/paths/~1pet/post/requestBody/content/application~1json/examples/pet-example
 - Message: Required "in" field is missing or is set to an invalid value, Location: #/paths/~1pet/put/parameters
 - Message: Required "in" field is missing or is set to an invalid value, Location: #/paths/~1pet~1findByStatus/get/parameters
 - Message: Required "description" field is missing or is set to an invalid value, Location: #/paths/~1pet~1findByStatus/get/responses/200
 - Message: Required "name" field is missing or is set to an invalid value, Location: #/paths/~1store~1order/post/parameters
 - Message: Required "in" field is missing or is set to an invalid value, Location: #/paths/~1store~1order/post/parameters
 - Message: Required "name" field is missing or is set to an invalid value, Location: #/paths/~1user~1{username}/put/parameters
 - Message: Required "in" field is missing or is set to an invalid value, Location: #/paths/~1user~1{username}/put/parameters
 - Message: Required "name" field is missing or is set to an invalid value, Location: #/paths/~1user~1createWithArray/post/parameters
 - Message: Required "in" field is missing or is set to an invalid value, Location: #/paths/~1user~1createWithArray/post/parameters
 - Message: Required "name" field is missing or is set to an invalid value, Location: #/paths/~1user~1createWithList/post/parameters
 - Message: Required "in" field is missing or is set to an invalid value, Location: #/paths/~1user~1createWithList/post/parameters
 - Message: Required "name" field is missing or is set to an invalid value, Location: #/paths/~1user/post/parameters
 - Message: Required "in" field is missing or is set to an invalid value, Location: #/paths/~1user/post/parameters ```

[MikeEdgar]

@EricWittmann - is the apiKey/api_key header in PetResource#deletePet (extracted in snippet below) an example of this? The TCK tests for apiKey, but I would expect a scanner to use the JAX-RS name api_key, particularly when the @Parameter is attached to the same argument/bean property as the JAX-RS annotation.

@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

[EricWittmann]

No although that seems wonky for a different reason (namely that the names do not match).

But an example of this issue, I think, is this:

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

Lines 97 to 101 in ac854fe

	@Parameter(
	description = "Created user object",
	schema = @Schema(ref = "#/components/schemas/User"),
	required = true
	) User user) {

That's a POST operation with a request body of type User which is annotated with @Parameter instead of @RequestBody.

[MikeEdgar]

Ok, I see now. I opened up #390 to take a look at clarifying parameter annotation usage and behavior.

[lamtrhieu]

Hi @EricWittmann @MikeEdgar
Is this something that need to work on ? I think this one could be a good one for me to understand more about all the open-api annotations.

[MikeEdgar]

@EricWittmann , @lamtrhieu - are either of you still interested in working on this one? I think this could be a good candidate to fix for 3.1.