我正在尝试为我的 api 创建一个大摇大摆的文档，我有点陷入了我认为一旦你知道怎么做就很容易实现的东西上。
我有一个端点，它接受多部分/表单数据形式的帖子(因为它需要文件上传(，但是其中一个项目(在本例中假装它被称为"carParts"(是一个 FormURLEncoded内容类型，它是键/值对的列表。
所以结构是这样的：
汽车名称：福特
车龄：20
汽车零件：车轮=4&喇叭=真&挡风玻璃=坏了
我的问题是我不确定如何在招摇的文档中表达这一点("carParts"(。
我能看到的唯一方法是将"carParts"项设置为字符串类型，但随后我失去了招摇的意义，因为我希望"轮子"，"喇叭"和"挡风玻璃"是显式字段，而不仅仅是单个表单url编码的字符串。
可以大摇大摆地做到这一点吗？
如果没有，我想唯一的其他选择是将我的 api 更改为仅将"carParts"项目作为平面列表而不是结构(即丢失"carParts"父级别并让项目只是其他顶级表单数据项目(。 这似乎是最直接的方法，但是如果我需要修改api来实现这一点，那就太可惜了(不是主要问题，只是感觉不对(。
这在OpenAPI 3.0中是可能的，但在OpenAPI/Swagger 2.0中则不然。
在 OpenAPI/Swagger 2.0 中，表单字段不能是对象，因此您必须carParts定义为字符串或原语数组。
在 OpenAPI 3.0 中，您可以在表单域中包含对象，并且可以指定如何序列化这些对象。目前的例子不多，但我认为您的案例可以描述如下：
paths:
/something:
post:
requestBody:
required: true
content:
multipart/form-data:
# Form fields (carName, etc.) are defined as object properties
schema:
type: object
properties:
carName:
type: string
carAge:
type: string
carParts:
type: object
properties:
wheels:
type: integer
horn:
type: boolean
windscreen:
type: string
# By default, the "carParts" object will be serialized as application/json,
# but we can override the serialization method to be form-urlencoded
encoding:
carParts:
contentType: application/x-www-form-urlencoded
规范的相关部分：多部分内容的特殊注意事项。