No way to specify a SchemaType.ARRAY items schema

…unless Im missing something.

Having a resource returning a List of pojos, and having to override the @ApiResponse to provide headers documentation, there seem to be no way to specify the response array schema. More generally, the @Schema annotation does not produce correct output for ARRAY types.

Considering the following resource:

@Path("search")
    @POST
    @Valid
    @Operation(summary = "Search point of sales", operationId = "searchPointOfSales")
    @APIResponses({@APIResponse(
            headers = {@Header(name = ApiParameters.LIST_RESULTS_COUNT_HEADER,
                    schema = @Schema(type = SchemaType.INTEGER),
                    description = "The amount of point of sales matching the filter")},
            content = @Content(schema = @Schema(description = "The search result page",
                    type = SchemaType.ARRAY,
                    implementation = WsPos.class)),
            description = "Search results"
    )})
    List<WsPos> findPosList(
            @BeanParam PaginationParams paginationParams,
            @RequestBody(description = "The point of sale filter", required = true)
            @Valid WsPosSearch wsPosSearch
    );

The generated yaml:

/pos/search:
    post:
      summary: Search point of sales
      operationId: searchPointOfSales
      requestBody:
        description: The point of sale filter
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WsPosSearch'
        required: true
      responses:
        default:
          description: Search results
          headers:
            X-Comptoir-ListTotalCount:
              description: The amount of point of sales matching the filter
              style: simple
              schema:
                type: integer
          content:
            application/json:
              schema:
                description: The search result page
                required:
                  - companyRef
                type: array
                properties:
                  companyRef:
                    description: Company reference
                    required:
                      - id
                    properties:
                      id:
                        format: int64
                        type: integer
                      link:
                        type: object
                  defaultCustomerRef:
                    type: object
                    properties:
                      id:
                        format: int64
                        type: integer
                      link:
                        type: object
                  description:
                    type: array
                    items:
                      type: object
                      properties:
                        locale:
                          type: object
                        text:
                          type: string
                  id:
                    format: int64
                    type: integer
                  name:
                    type: string

is invalid - the response schema needs an items property.

By not specifying the @ApiResponse, the generated yaml is correct, but lacks the header documentation. By specifying the @ApiResponse without the content parameter, the generated yaml does not contain any schema for the response. By specifying the @ApiResponse with the content parameter, the @Schema annotation lacks a parameter to specify the array items schema and thus produces invalid yaml.

Using smallrye-openapi:1.1.1 (wildfly thorntail 4.2.0.Final).

[arthurdm]

Thanks for opening this @cghislai. We agreed in the hangout that the spec API already supports this, as per this snippet:

@Schema(description = "The search result page",
                    type = SchemaType.ARRAY,
                    implementation = WsPos.class)

The bug in smallrye has been fixed, so closing this issue.

[Ladicek]

Thorntail master is currently on SmallRye OpenAPI 1.1-1.0.1. I see there’s 1.1-1.0.2 out, so I’ll make sure Thorntail is updated to that before the 2.5.0 release.