swagger 文档中的查询字符串参数未在请求中作为数组发送

Question

我目前正在使用 Symfony 4.3.4 和 API 平台 v2.3.6.

我现在面临 1 个问题。假设我使用名为 products 的查询字符串参数向 enpoint 发送 GET 请求，因为我发送了 1 或更多 产品 ID。

我想在我的控制器中获取产品参数的值作为 PHP 数组。

所以我的要求是

GET /my/endpoint?products[]=8f391c60-5467-4bf0-917f-e2151337fa7e&products[]=ddaa94e1-af79-4abf-9dfc-a28dd8077f45

我在控制器中执行转储：

dump($request->query->get("products"));

然后我得到：

array:2 [
  0 => "8f391c60-5467-4bf0-917f-e2151337fa7e"
  1 => "ddaa94e1-af79-4abf-9dfc-a28dd8077f45"
]

如您所见，我在查询字符串中像数组一样传递产品 ID 的方式，我可以将产品参数检索为 PHP 数组。我在这里关心的是招摇的文档。在 YAML 中使用此配置：

collectionOperations:
    operation_name:
        method: get
        path: /my/endpoint
        controller: App\Controller\MyEndpointController
        swagger_context:
            summary: My summary
            description:
                My endpoint description
            responses:
                parameters:
                    -
                        in: query
                        name: products
                        description: "The products IDs parameter"
                        schema:
                            type: array
                            items:
                                type: "string"
                                example: "019fcd9b-beea-4791-8a59-d4e2d02427d6"

在API文档页面中，当我选择试用时，我必须填写包含的所有参数值产品.问题是产品参数显示为 文本输入 。

如果我在参数的 yaml 配置中删除 schema 键，我将 type: array 和 items 键直接放在与 in、name 和 description：

parameters:
    -
        in: query
        name: products
        description: "The products IDs parameter"
        type: array
        items:
            type: "string"
            example: "019fcd9b-beea-4791-8a59-d4e2d02427d6"

然后产品参数出现，带有添加项目按钮。每次我点击这个按钮，我可以填写一个产品ID来通过，就可以了。问题是，当我单击执行时（仍在 API 文档页面中）我有一个错误，因为 API 平台不会发送带有产品参数的请求作为真正的数组，而是作为包含所有内容的字符串以 ,:

分隔的产品 ID

GET /my/endpoint?products=8f391c60-5467-4bf0-917f-e2151337fa7e,ddaa94e1-af79-4abf-9dfc-a28dd8077f45

这就是我想要的：

GET /my/endpoint?products[]=8f391c60-5467-4bf0-917f-e2151337fa7e&products[]=ddaa94e1-af79-4abf-9dfc-a28dd8077f45

关于使用 API 平台实现此目的的方法有什么想法吗？

Answer 1

查询参数需要命名为products[]（带方括号）并且具有collectionFormat: multi属性：

parameters:
  - in: query
    name: products[]
    type: array
    items:
      type: string
      format: uuid
    collectionFormat: multi
    # (Optional) Array example to display in Swagger UI
    x-example:
      - 8f391c60-5467-4bf0-917f-e2151337fa7e
      - ddaa94e1-af79-4abf-9dfc-a28dd8077f45

注意OpenAPI 2.0中的查询参数do not support是example关键字，但一些工具（如SwaggerUI）支持x-example扩展来指定示例查询参数的值。

swagger 文档中的查询字符串参数未在请求中作为数组发送

Query string parameter in swagger documentation not sent as array in request

rest

symfony

swagger

api-platform.com