Swagger 2.0支持矩阵参数吗？

Question

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

JAX-RS 规范有Matrix-Parameter支持。

我的应用程序中存在一些矩阵参数，例如

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

。 我想为矩阵参数导出 Swagger。我使用 http://editor.swagger.io；但我无法在编辑器中得到任何帮助。有人可以帮助我吗？

Swagger 2.0支持矩阵参数吗？

与矩阵参数相关的其他链接：

• 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 不支持矩阵参数，但在 OpenAPI 3.x 中支持。

使用 OpenAPI 3，您的示例：

/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注释的人，swagger-core 2.0支持

@MatrixParam

。

@MatrixParam

对应 OpenAPI 3 的带有

style: matrix

的路径参数（如上例所示）。

Answer 2

Swagger 2.0 规范没有提及任何有关 JAX-RS Matrix 参数的内容。

同时查看 swagger-jaxrs 实现，您可以看到

@MatrixParam

在负责扫描 JAX-RS 参数注释的类中被忽略。