如何在我的 YAML Swagger 定义中将属性类型定义为字符串的列表（列表、集合、数组、集合）

Posted 2023-02-26

【中文标题】如何在我的 YAML Swagger 定义中将属性类型定义为字符串的列表（列表、集合、数组、集合）

【英文标题】：How can I define a property type as being a list (list, set, array, collection) of string in my YAML Swagger definition

【发布时间】：2016-11-27 23:01:16

【问题描述】：

我正在为一个 API 编写一个 swagger 定义文件。该 API 用于 GET 请求

/path/to/my/api:
  get:
    summary: My Custom API
    description: |
      Gets a List of FooBar IDs
    produces:
      - application/json
    tags:
      - FooBar
    responses:
      "200":
        description: successful operation
        schema:
          $ref: "#/definitions/MyCustomType"         

...

MyCustomType:
  type: object
  properties: 
    myCustomObject
      type: ??? # list of string?

【参考方案1】：

对于字符串列表，可以这样描述：

      type: array
      items:
        type: string

参考：https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject

例子：

https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml#L93-L100 (OpenAPI v2) https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml#L71-L78 (OpenAPI v3)

【讨论】：

给定的示例是针对数组/列表的，那么设置呢？无法从谷歌获得线索

【参考方案2】：

这些 cmets 似乎都没有真正回答这个问题——如何在 OpenAPI/Swagger 中定义一组项目？

字符串数组与 SET 不同 唯一字符串数组与 SET 不同

集合本质上是一组不重复的枚举值。

给定可能的字符串值facebook、pinterest、twitter，名为share_type 的字段的值可能包含其中的一个或多个，例如：

有效

facebook twitter facebook, twitter facebook, twitter, pinterest

无效项目

instagram facebook, instagram pinterest, pinterest

另一个重要的区别是值不能重复。这就是uniqueItems 指令可以提供帮助的地方。

鉴于上面的示例，OpenAPI 规范可能如下所示：

share_type:
  type: array
  uniqueItems: true
  items:
    type: string
    enum:
      - facebook
      - pinterest
      - twitter