OpenAPI, @Parameter on parameter ignored?

[Tim Quinn]

I haven't dug into this too deeply, but it seems that OpenAPI 1.1.2 ignores a `@Parameter` annotation on a parameter. In this case, there is also a `@PathParam` annotation; I'm not sure if that's important or not.

If, though, I move the `@Parameter` annotation to the method level, then it's recognized and matched up with the parameter. 

Here's a very simple example: https://github.com/tjquinno/helidon/blob/0be4b63cfaadd04ac55cb4ba716716117b396d09/examples/microprofile/openapi-basic/src/main/java/io/helidon/microprofile/examples/openapi/basic/GreetResource.java#L114-L117

    @Parameter(name = "name", description = "Not ignored")

    public JsonObject getMessage(

            @Parameter(description = "This is ignored")

            @PathParam("name") String name) {

I searched this group and the OpenAPI issues and didn't see anything that seemed relevant. Have I missed something? 

Thanks.

[Michael Edgar]

Hi Tim,

Are you expecting that the attributes of the `@Parameter` on the method will be merged with the attributes of the annotation on the parameter itself? I did a test of this and it did apply the annotation from the method parameter as expected. The additional annotation on the method "overrides" the one directly on the parameter.

Thanks

--
You received this message because you are subscribed to the Google Groups "SmallRye" group.
To unsubscribe from this group and stop receiving emails from it, send an email to smallrye+u...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/smallrye/98764212-2960-4284-b04c-6c4997062663n%40googlegroups.com.

[Tim Quinn]

Sorry, Michael. I posted a confusing example.

I've updated the code snippet to better reflect the problem:

https://github.com/tjquinno/helidon/blob/845e6df3265d8a5b8a1b487d12e35534c9063de5/examples/microprofile/openapi-basic/src/main/java/io/helidon/microprofile/examples/openapi/basic/GreetResource.java#L114-L117

```

    //@Parameter(name = "name", description = "Not ignored")

    public JsonObject getMessage(

            @Parameter(description = "This is ignored")

            @PathParam("name") String name) {

```

Here I've commented out the method-level `@Parameter` annotation, so only the parameter-level one remains (with `@PathParam`).

This way, I do not see the description I expect for the parameter in the OpenAPI document.

If I uncomment the method-level annotation, then I see the description it specifies in the output.

And it's not just `description`. Specifying `allowEmptyValue` as `true` (not the default value) in the parameter-level annotation is also ignored while it is recognized in the method-level annotation.

[Michael Edgar]

Tim,

If I process the linked `GreetResource` through the scanner, I see what I believe to be the expected result. Which release of smallrye-open-api is Helidon using?

```

    "/greet/{name}" : {
      "get" : {
        "summary" : "Returns a personalized greeting",
        "parameters" : [ {
          "name" : "name",
          "in" : "path",
          "description" : "This is ignored",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "default" : {
            "description" : "Simple JSON containing the greeting",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/GreetingMessage"
                }
              }
            }
          }
        }
      }
    }

```

Thanks,

Mike

To view this discussion on the web visit https://groups.google.com/d/msgid/smallrye/b03a6402-cad9-440f-a343-c98a3d425a41n%40googlegroups.com.

[Tim Quinn]

Thanks, Mike.

We're still on 1.2.0. I tried locally with 1.2.3 and got the same results. 1.2.4 added `getSchemas` to `io.smallrye.openapi.api.OpenApiConfig` which we extend and we haven't addressed that to be able to move to a later release. I should be able to do that soon -- at least locally -- and see if using a later release helps.

- Tim

[Tim Quinn]

Hi, Mike.

Finally getting back to this.

I made some changes to our code to use SmallRye OpenAPI 2.0.8 to make sure I've got the latest and greatest. 

I'm seeing the same problematic behavior with the same example code.

Stepping through the code, I see `@PathParam` processed first (not that it should matter), then the argument-level `@Parameter` annotation.

As the code processes the `@Parameter` annotation, `ParameterProcessor#getParameterContext` tries to find the pre-existing context for the parameter. To me there seemsto be  one — with key `name: name, in: path` but the key passed to `getParameterContext` associated with the `@Parameter` annotation is `name: name, in: null`. That's OK on the surface, I think, but the code does not find the pre-existing context using any of the three attempts:

• in the map directly (this seems expected),
  
• using `haveSameAnnotatedTarget` in 1205:1211 (to me, this is a surprise), or
• the "last chance" check at the end of the method.

I'm guessing that the intent was that `haveSameAnnotatedTarget` would return `true` for this case, given that the pre-existing context entry created from the `@PathParam` and the context being created for the parameter-level `@Parameter` annotation would (to me, at least) have the same target. 

I did not see that `MethodParameterInfo` implements `equals`, so it would inherit the implementation from `Object` which does a simple `==` comparison of the two object references. And, indeed, the code is comparing two different instances of `MethodParameterInfo` although they look to me to be referring to the same target. 

If `haveSameAnnotatedTarget` returned `true` here, then I think the rest of the code would combine the information from the two annotations. As it is, I see two contexts in the processor's `params` collection where I'd expect to see a single, combined context for the parameter.

But maybe there's more to it that I'm missing.

I can't explain why you and I are getting different results unless maybe the order in which the `@PathParam` and `@Parameter` annotations are dealt with does matter and for some reason our test runs process them in different orders.

Maybe if `MethodParameterInfo` overrode `equals` the order wouldn't matter (if in fact that's the problem). Maybe it should implement `equals` anyway? 

If there's anything else I can try from here, please let me know. For the moment I'm not sure what I might be doing to cause the problem.

Thanks.

- Tim

[Michael Edgar]

Tim,

The current release on the 2.0.x branch is 2.0.17. Please try that version and let me know if it resolves the issue. There were definitely bug fixes in the parameter matching code along the way in 2.0.x.

Thanks,

Mike

To view this discussion on the web visit https://groups.google.com/d/msgid/smallrye/527ea81b-0a49-44ec-8956-7d6693287107n%40googlegroups.com.

[Tim Quinn]

Hi, Mike.

Using 2.0.17 I see the same problem.

I see `ParameterProcessor#haveSameAnnotationTarget` incorrectly (I think) returning `false` due to (again, I think) the combination of line 1237 using `target.equals` (which uses `Object.equals`, which compares references) and the caller passing in a different instance of `AnnotationTarget` vs. what's stored in the `context`. 

- Tim

[Michael Edgar]

Hi Tim,

Sorry, I lost track of this. Would you mind opening an issue in the smallrye-open-api repository and we can work through it?

https://github.com/smallrye/smallrye-open-api

Thanks,

Mike

To view this discussion on the web visit https://groups.google.com/d/msgid/smallrye/3a5e1404-569f-43c2-b40b-6bd3fe84338dn%40googlegroups.com.

[Tim Quinn]

https://github.com/smallrye/smallrye-open-api/issues/646