如何使用 OpenAPI 3.1 和 Nelmio 渲染哈希图？

Question

我想在我的API文档的Response schema和Response samples（examples）部分中正确渲染

hashmap

（

key

：UUID，value：对象），例如：

{
  "objects": {
    "3a34655e-9566-4d5e-bce7-8fa71670993b": {
      "title": "Foo"
    },
    "4bb806a9-fcd1-4a32-b2f0-6cbb45cfc894": {
      "title": "Bar"
    }
  }  
}

我正在使用这些库开发 Symfony 6 项目，这些库应该与 OpenAPI 3.0 和 3.1 规范兼容：

• zircote/swagger-php

  （版本：

  4.7.10

  ）

• nelmio/api-doc-bundle

  （版本：

  v4.11.1

  ）

阅读相关的 StackOverflow 答案，我考虑了 2 个选项：

选项 1 - 附加属性

/**
 * @var array<string, ObjectDto>
 *
 * @OA\Property(
 *     type="object",
 *     @OA\AdditionalProperties(
 *         type="object",
 *         ref=@Model(type=ObjectDto::class),
 *     ),
 *     description="The objects indexed by ID"
 * )
 */

问题

我没有找到任何方法来覆盖默认分配给

property name*

部分中渲染的哈希图键的

Response schema

，也没有找到任何方法来

"property1"

部分中渲染的

"property2"

和

Response samples

：

"objects": {
    "property1": { ... },
    "property2": { ... }
},

我可以自定义密钥的信息

选项 2 - 模式属性

    /**
     * @var array<string, ObjectDto>
     *
     * @OA\Property(
     *     type="object",
     *     patternProperties={
     *         "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"=@OA\Property(
     *             type="object",
     *             ref=@Model(type=ObjectDto::class),
     *         )
     *     },
     *     description="The objects indexed by ID"
     * )
     */

问题

Response schema

部分没问题，但是

Response samples

部分生成的示例是空，我得到：

"objects": { }

问题

我错过了什么吗？是否可以使用 OpenAPI 规范 3.1 完全控制哈希图的渲染？

Answer 1

OpenAPI 3.0似乎不支持使用，甚至不支持模仿patternProperties的效果。你会在他们的一些提案中看到它，但截至2023年9月，它还没有实现。您需要将映射对象转换为描述键值对的数组，无论是对象数组还是元组。或者您可能会站在我的立场上，无法从后端更改数据的表示形式，并为类型安全的损失而默默哭泣。

Original Value:
    { myHashMap: { uniqueKey1: ..., uniqueKey2: ... }}

----Converted to objArray: ----------------------
{ myHashMap: [
    {id: uniqueKey1, value: ...},
    {id: uniqueKey2, value: ...}
  ]
} 

----Converted to tuple: ----------------------
{ myHashMap: [
    [uniqueKey1, ...(value)],
    [uniqueKey2, ...(value)]
  ]
}

---

我花了很长时间才弄清楚这一点，答案就在此页。 OpenAPI 使用 jsonSchema 的修改版本来描述对象，它支持额外的键，并放弃对其他键的支持，包括我们心爱的模式属性。

不支持的[jsonSchema]关键字：

• 额外物品
• 常量
• 包含
• 依赖关系
• id，
• $id
• 模式属性 <------------
• 属性名称

他们提供了以下页面，其中提供了有关处理字典、哈希映射等的信息 - 尽管我找不到有关特定键处理模式的信息。