Search code examples
javamavenswagger

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

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!

Solution

  • 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.