Why are Matrix parameters always generated as required by Swagger / OpenAPI plugin?

Question

In our Java code, we annotate our REST endpoints with Swagger annotations to document them. However, regardless whethere a Matrix parameter is configured as required or not, it is generated in the openapi.yaml as required.

Here's the parameter in Java:

  @Parameter(required = false, allowEmptyValue = false)
  @MatrixParam("fristId") final Integer fristId

We use the Maven plugin io.openapitools.swagger:swagger-maven-plugin:2.1.6 which generates the following:

      parameters:
      - name: fristId
        in: path
        required: true
        style: matrix
        schema:
          type: integer
          format: int32

Am I doing something wrong? Is this a bug in the plugin? Any help is greatly appreciated!

score 0 · Accepted Answer · answered Jun 06 '23 at 18:00

This is because matrix parameters are URL path parameters, and path parameters are always required according to the OpenAPI Specification.

To have an optional path parameter, you'll have to define 2 paths - one with and one without that parameter.

Other parameter types - query, header, cookie, and form parameters - can be either required and optional.

Why are Matrix parameters always generated as required by Swagger / OpenAPI plugin?

1 Answers1