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

Question

我正在为 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?

Answer 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）

Answer 2

None 这些评论似乎真的回答了这个问题——你如何在 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