5

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:

Helen
  • 87,344
  • 17
  • 243
  • 314
Moon Mysterious
  • 164
  • 1
  • 14

2 Answers2

2

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:

Matrix parameters in Swagger UI

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

Helen
  • 87,344
  • 17
  • 243
  • 314
1

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.

Navid Shakibapour
  • 555
  • 3
  • 7
  • 2
    There is a proposal in the next version to support them. Not sure if it'll happen, but you can follow it if you like: https://github.com/OAI/OpenAPI-Specification/issues/69 – fehguy Mar 14 '16 at 17:44
  • `@MatrixParam` is now supported in swagger-core 2.0 and corresponds to OpenAPI 3.0's `style: matrix`. – Helen May 21 '18 at 14:59