[doc] [java/spring] x-YYY-extra-annotation doc is misleading

[elonderin]

Description

the current java/spring doc reads:

List of custom annotations to be added to YYYY

So i was thinking: ok, i can write a yaml list if all my annotations that i want to add. eg.

      properties:
        foo:
          type: string
          x-field-extra-annotation:
            - "@MyCustomAnnotation1"
            - "@MyCustomAnnotation2"

WRONG

First one needs to understand that annotation in x-field-extra-annotation has nothing to do with java annotations even though the description suggests that IMO.

Second, there is no "List" here in a syntactical yaml/json sense, rather this extension may be used to add a list of java annotation there, but also a myriad of other things.

What this really does, is:

1. create a json-ish string from the value of x-field-extra-annotation (ie drop the quotes, replace : -> = )
2. put that as a text above the field

Hence, a more fitting name to the current behavior would be x-field-extra-text-above.

example:

        value:
          x-field-extra-annotation:
            foo:
              bar:
                 - 123
                 - ASDASD

will do this:

  {foo={bar=[123, ASDASD]}}
  private String value;

openapi-generator version

6.6.0

[borsch]

@elonderin sorry, can't get what's your concerns. Probably description for this extension missing proper usage example but rest is correct. It's used to add annotation(s) over the field. Here is usage sample

https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/test/resources/3_0/issue_11772.yml

and internal test that is used to verify behaviour https://github.com/OpenAPITools/openapi-generator/blob/389270334a4f6e1f969bd3baabf011e18942f858/modules/openapi-generator/src/test/java/org/openapitools/codegen/TestUtils.java#L257

[elonderin]

i would write the doc for these extensions like this:

The text value provided here is written verbatim above the class/field/setter. The most common use case is to add specific java annotations, see (link to an example)