Swagger 2.0 是否支持矩阵参数？答案

【问题标题】：Does Swagger 2.0 support matrix parameters?Swagger 2.0 是否支持矩阵参数？
【发布时间】：2016-03-11 07:30:15
【问题描述】：

Swagger 2.0 是否支持 JAX-RS 规范的矩阵参数？

JAX-RS specification 有 Matrix-Parameter 支持。

我的应用程序中有一些矩阵参数，例如/map/color;lat=50;long=20;scale=32000。我想为矩阵参数派生 Swagger。我用http://editor.swagger.io；但我在编辑器中得不到任何帮助。谁能帮帮我？

Swagger 2.0 是否支持矩阵参数？

其他链接到矩阵参数：

【问题讨论】：

标签： swagger swagger-2.0 swagger-editor

【解决方案1】：

OpenAPI/Swagger 2.0 不支持矩阵参数，但 OpenAPI 3.0 支持。

使用 OpenAPI 3.0，您的示例：

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

可以定义为：

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/编辑器支持

这在 Swagger UI 3.15.0+ 和 Swagger Editor 3.5.6+ 中受支持。在参数编辑器中，输入 JSON 对象格式的参数名称和值，例如：

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

“试试看”会将这些参数作为矩阵参数发送到 URL：

Swagger 核心支持

对于那些使用 Java 注释的人，@MatrixParam 在 swagger-core 2.0 中得到支持。 @MatrixParam 对应 OpenAPI 3.0 的路径参数 style: matrix（如上例所示）。

【讨论】：

【解决方案2】：

Swagger 2.0 spec 没有提及 JAX-RS Matrix 参数。

同样查看swagger-jaxrs实现，可以看到@MatrixParam在负责扫描JAX-RS参数注解的the class中被忽略了。

【讨论】：

在下一个版本中有一个支持它们的提案。不确定它是否会发生，但如果您愿意，可以关注它：github.com/OAI/OpenAPI-Specification/issues/69
@MatrixParam 现在在 swagger-core 2.0 中得到支持，对应于 OpenAPI 3.0 的 style: matrix。