swagger 如何从引用的架构中排除属性?

iyfamqjs  于 2023-06-22  发布在  其他
关注(0)|答案(2)|浏览(398)

我有一个端点来创建一个地址,还有一个端点来更新它。在OpenAPI规范中描述这一点时,我想使用一个组件作为地址,这样就不必两次指定地址。现在的问题是,用于更新的address对象应该包含属性“id”,但用于创建的地址对象没有。
所以基本上,我正在寻找一种方法来描述完整的地址(包括。id属性),然后引用create端点,但不包括“id”属性。

zbdgwd5y

zbdgwd5y1#

可以使用allOf关键字as documented here扩展另一个类型
在下面的示例中,creationType只有name属性,但updateType具有creationType的所有属性以及id属性。
示例:

components:
  schemas:
    creationType:
      type: object
      properties:
        name:
          type: string
    updateType:
      allOf:
      - $ref: '#/components/schemas/creationType'
      - type: object
        required:
        - id
        properties:
          id:
            type: string
gg0vcinb

gg0vcinb2#

您可以使用readOnly关键字来实现这一点,它提供了一种标准化的方法来实现所需的结果。
可以使用readOnly和writeOnly关键字将特定属性标记为只读或只写。例如,当GET返回的属性多于POST中使用的属性时,这很有用-您可以在GETPOST中使用相同的模式,并将额外的属性标记为readOnly。readOnly属性包含在响应中,但不包含在请求中,而writeOnly属性可以在请求中发送,但不包含在响应中。
示例:

type: object
properties:
    id:
        # Returned by GET, not used in POST/PUT/PATCH
        type: integer
        readOnly: true
    username:
        type: string
    password:
        # Used in POST/PUT/PATCH, not returned by GET
        type: string
        writeOnly: true

如果readOnlywriteOnly属性包含在required列表中,则required仅影响相关范围-仅响应或仅请求。也就是说,只读必需属性仅应用于响应,只写必需属性仅应用于请求。
参见文档:文献资料

Petstore示例:

请注意,我们对负载和响应使用了相同的模型。但是,由于readOnly属性被设置为true,因此id属性被排除在有效负载之外。

...
        Pet:
            required:
                - name
                - photoUrls
            type: object
            properties:
                id:
                    type: integer
                    format: int64
                    example: 10
                    readOnly: true
...

相关问题