Question

我正在使用swagger编写REST API，而且我在定义与jsonapi格式（jsonapi.org）一致的易于阅读的规范时遇到了问题。该问题特定于所包含资源的定义。

我有多个包含所有不同属性的资源。

"included": [{
                "type": "author",
                "id": "323454",
                "attributes": {
                  "1": "Bob",
                  "2": "Jim"
                },
              {
                "type": "book",
                "id": "323454",
                "attributes": {
                  "3": "The Island"
                  "4": "The Other Island"
                }]

我尝试在包含的数组下定义多个$ ref对象，但这不起作用：

  included:
    type: array
    items: 
      - $ref: "#/definitions/includedResource"
      - $ref: "#/definitions/includedResource2"
      - $ref: "#/definitions/includedResource3"

有没有很好的方法来设置多个可选对象？我不想调出一个资源对象中的所有属性，因为它不容易读取或将属性与资源对齐。

Answer 1

在OpenAPI（fka Swagger）2.0中，数组项必须只是相同类型，例如所有字符串或全部includedResource。

除非我误解了某些内容，否则可以使用includedResource的单个架构来描述您的示例，attributes属性是关联数组/字典。

definitions:
  included:
    type: array
    items:
      $ref: '#/definitions/includedResource'

  includedResource:
    type: object
    # required: [type, id, attributes] # Indicate the required properties if needed
    properties:
      type:
        type: string
        # enum: [author, book] # Use enum if needed
      id:
        type: string
      attributes:
        type: object
        additionalProperties: 
          type: string

Swagger中包含的资源

1 个答案: