Does Swagger 2.0 support matrix parameters?

Question

Does Swagger 2.0 support matrix parameters of JAX-RS specification?

JAX-RS specification have Matrix-Parameter support.

I have some matrix parameter present in my application such as /map/color;lat=50;long=20;scale=32000. I want to derive Swagger for matrix parameters. I use http://editor.swagger.io; but I could not got any help in the editor. Can anyone help me?

Does Swagger 2.0 support matrix parameters?

Other links ralted to matrix param:

• https://www.w3.org/DesignIssues/MatrixURIs.html
• https://www.safaribooksonline.com/library/view/restful-java-with/9780596809300/ch05s03.html

Answer 1

OpenAPI/Swagger 2.0 does not support matrix parameters, but they are supported in OpenAPI 3.0.

Using OpenAPI 3.0, your example:

/map/color;lat=50;long=20;scale=32000

can be defined as:

openapi: 3.0.1
...
paths:
  /map/color{params}:
    get:
      parameters:
        - in: path
          name: params
          required: true

          # Named matrix parameters are defined as object properties
          schema:
            type: object
            properties:
              lat:
                type: integer
                example: 50
              long:
                type: integer
                example: 20
              scale:
                type: integer
                example: 32000

          # Serialize this object as ;prop1=value2;prop2=value2 etc
          style: matrix
          explode: true

Swagger UI/Editor Support

This is supported in Swagger UI 3.15.0+ and Swagger Editor 3.5.6+. In the parameter editor, enter the parameter names and values in the JSON object format, e.g.:

{
  "lat": 50,
  "long": 20,
  "scale": 32000
}

"Try it out" will send these parameters as matrix parameters in the URL:

Swagger-Core Support

For those using Java annotations, @MatrixParam is supported in swagger-core 2.0. @MatrixParam corresponds to OpenAPI 3.0's path parameters with style: matrix (as in the example above).

Answer 2

Swagger 2.0 spec does not mention anything about JAX-RS Matrix parameter.

Also looking at the swagger-jaxrs implementation, you can see that @MatrixParam is ignored in the class responsible for scanning JAX-RS parameter annotations.