Warning on referenced example

[EstebanDugueperoux2]

Describe the bug
I'm developing HTTP JSON API based on SpringDoc OpenAPI3, but to avoid JSON example formating issues, I prefer to externalize them and reference them like that:

  @ApiResponses(value = {
      @ApiResponse(responseCode = "200", description = "Blabla", content = {
          @Content(schema = @Schema(implementation = SearchResults.class), examples = @ExampleObject(ref = "#/components/examples/http200SearchCharacteristicsExample")) }) })
  public ResponseEntity<SearchResults> searchCharacteristics(){
...
}

And in a @configuration class, I use a OpenApiCustomiser to provide these examples.

The issue is that if I don't provide @example's name, it doesn't appears in generated swagger.
And if I provide a name like:

@ExampleObject(name = "http200SearchCharacteristicsExample", ref = "#/components/examples/http200SearchCharacteristicsExample")) }) })
  public ResponseEntity<SearchResults> searchCharacteristics(){
...
}

It appears but with a description attribute:

  examples:
                200GetCharacteristics:
                  description: 200GetCharacteristics
                  $ref: '#/components/examples/http200GetCharacteristicsExample'

which make a warning using https://editor.swagger.io/ saying "Sibling values are not allowed alongside $refs". If I remove manually "description" attribute I have no more this warning.
Indeed this description is redundant with one from '#/components/examples/http200GetCharacteristicsExample'.

When analyzing I see an issue in org.springdoc.core.SpringDocAnnotationsUtils.setExamples(MediaType, ExampleObject[])
which don't consider ref when a single example is provided without name but consider it as an embedded example.

[bnasslahsen]

@EstebanDugueperoux2,

Can you add the complete example on your description, in order to address it.

Please have a look at out contribution guide on the section Using GitHub Issues:

• https://github.com/springdoc/springdoc-openapi/blob/master/CONTRIBUTING.adoc

[EstebanDugueperoux2]

Having forked https://github.com/springdoc/springdoc-openapi-demos in https://github.com/EstebanDugueperoux2/springdoc-openapi-demos/commit/47e750587cb91398cc70133c074c754bd582285a

To reproduce, launch springdoc-openapi-test-app2 example:

mvn clean spring-boot:run

Get swagger from http://localhost:8080/v3/api-docs/users,
format it with https://jsonformatter.curiousconcept.com/ and see referenced example having a description while referencing operation has also a description equals to its name:

"examples":{ "500":{ "description":"500", "$ref":"#/components/examples/http500Example" } }

Check it with https://editor.swagger.io/ and see the warning.

[bnasslahsen]

I have added a fix for it; It will be available on v1.2.31.
I believe this should be fixed on the swagger-core on the following class:
io.swagger.v3.core.util.getExample(ExampleObject example) which should ignore description when of $ref is present.

[EstebanDugueperoux2]

Thanks.