Override description for items in array schema

[jochenberger]

I'm using OpenAPI 3.1.

I have the following classes:

    class Street {
        @ArraySchema(schema = @Schema(implementation = House.class, description = "A house in a street"))
        public List<House> houses;
    }

    @Schema(description = "A house")
    class House {
        public String number;
    }

The generated YAML looks like this:

Street:
type: object
properties:
  houses:
    type: array
    items:
      $ref: "#/components/schemas/House"

House:
type: object
description: A house
properties:
  number:
    type: string

The description for the items is not included.

If I remove the implementation = House.class from the inner schema definition, I get

Street:
type: object
properties:
  houses:
    type: array
    items:
      description: A house in a street

House:
type: object
description: A house
properties:
  number:
    type: string

Now the description is there, but the $ref is gone.
I'd expect the item definition to contain both the $ref and the description in both cases.

[jochenberger]

FTR, If I use OpenAPI 3.0, I only get the $ref in both cases, with and without the implementation = House.class.

[jochenberger]

For single-valued properties, the description can be set.
For example,

    class Street {
        @Schema(description = "The elected leader")
        public Person spokesPerson;
    }

results in

Street:
type: object
properties:
  spokesPerson:
    $ref: "#/components/schemas/Person"
    description: The elected leader

[jochenberger]

See also #4753

[jochenberger]

If seems to work if I use @ArraySchema(schema = @Schema(allOf = House.class, description = "A house in a street"))
I end up with

...
    type: array
    items:
      description: A house in a street
      allOf:
        - $ref: "#/components/schemas/House"

which is correct but unnecessarily complicated in OpenAPI 3.1.

[jochenberger]

With 2.2.28, I get the correct result with @ArraySchema(schema = @Schema(implementation = House.class, description = "A house in a street")), but it still does not work without the implementation = House.class. I think that this should be determined by the library.