OpenAPI 3模式继承的正确allOf语法是什么？

Question

哪种语法是正确的-第一种，第二种，还是两者都正确？

components:
  schemas:
    FileContent:
      allOf:
        - $ref: '#/components/schemas/FileInfo'
        - type: object
          properties:
            storageMethod:
              $ref: '#/components/schemas/StorageMethod'
            contentRange:
              type: string
              nullable: true
            # ... other properties ...
          additionalProperties: false

components:
  schemas:
    FileContent:
      type: object
      allOf:
        - $ref: '#/components/schemas/FileInfo'
      properties:
        storageMethod:
          $ref: '#/components/schemas/StorageMethod'
        contentRange:
          type: string
          nullable: true
        # ... other properties ...
      additionalProperties: false

Answer 1

我认为第二个：很长一段时间，json模式中忽略了与$ref相邻的模式关键字。后来他们在规范（AFAIK）中更改了它，但我不确定是否所有的工具

然而，我个人的偏好是将父模式和子模式属性放在＜code＞allOf＜code＞下，如

  schemas:
    FileContent:
      allOf:
        - $ref: '#/components/schemas/FileInfo'
        - type: object
          properties:
            storageMethod:
              $ref: '#/components/schemas/StorageMethod'
            contentRange:
              type: string
              nullable: true
            totalLength:
              type: integer
              format: int64

Answer 2

就< code>allOf语法而言，两个版本都是正确的，并且在技术上是等效的:

allOf:
  - $ref: '#/components/schemas/Foo'
  - properties:
      # other properties
      # ...

allOf:
  - $ref: '#/components/schemas/Foo'
properties:
  # other properties
  # ...

在OpenAPI 3.1（默认情况下使用JSON模式2020-12）中，如果您只有一个$ref的话，甚至不需要allOf，因为$ref现在允许同级关键字。（但您仍然需要＜code＞allOf

# openapi: 3.1.0

$ref: '#/components/schemas/Foo'
properties:
  # other properties
  # ...

您的示例中的错误在其他地方——它是< code > additional properties:false 的存在。这个关键字是有问题的，因为它只知道它的直接兄弟< code>properties，而看不到allOf/oneOf/anyOf子模式或“继承”模式。对于您的示例，这意味着在< code>FileInfo模式中定义的属性实际上不允许出现在组合模式中。

这里有一些更多的例子来说明additionalProperties： false并不像人们期望的那样工作：

allOf:
  - $ref: '#/components/schemas/Foo'
  - $ref: '#/components/schemas/Bar'
additionalProperties: false

# Expected: Only the properties defined in Foo and Bar are allowed
# Actual: No properties are allowed

allOf:
  - $ref: '#/components/schemas/Foo'
  - properties:
      prop:
        type: string
    additionalProperties: false

# Expected: The allowed properties are `prop` and those defined in the Foo schema
# Actual: Only the `prop` property is allowed

allOf:
  - $ref: '#/components/schemas/Foo'
properties:
  prop:
    type: string
additionalProperties: false

# Expected: The allowed properties are `prop` and those defined in the Foo schema
# Actual: Only the `prop` property is allowed

Foo:
  type: html" target="_blank">object
  properties:
    foo:
      type: string
  additionalProperties: false

Bar:
  allOf:
    - $ref: '#/components/schemas/Foo'
    - properties:
        prop:
          type: string

# Expected: The Bar schema allows properties from Foo + the `prop` property
# Actual: The Bar schema allows only properties from Foo

这在OpenAPI 3.1/JSON模式2019-09中通过新的＜code＞unevaluedProperties:false＜code＞关键字解决。因此，以下内容将按您预期的方式工作：

# openapi: 3.1.0

$ref: '#/components/schemas/Foo'
properties:
  prop:
    type: string
unevaluatedProperties: false