我有一个端点来创建一个地址,还有一个端点来更新它。在OpenAPI规范中描述这一点时,我想使用一个组件作为地址,这样就不必两次指定地址。现在的问题是,用于更新的address对象应该包含属性“id”,但用于创建的地址对象没有。所以基本上,我正在寻找一种方法来描述完整的地址(包括。id属性),然后引用create端点,但不包括“id”属性。
zbdgwd5y1#
可以使用allOf关键字as documented here扩展另一个类型在下面的示例中,creationType只有name属性,但updateType具有creationType的所有属性以及id属性。示例:
allOf
creationType
name
updateType
id
components: schemas: creationType: type: object properties: name: type: string updateType: allOf: - $ref: '#/components/schemas/creationType' - type: object required: - id properties: id: type: string
gg0vcinb2#
您可以使用readOnly关键字来实现这一点,它提供了一种标准化的方法来实现所需的结果。可以使用readOnly和writeOnly关键字将特定属性标记为只读或只写。例如,当GET返回的属性多于POST中使用的属性时,这很有用-您可以在GET和POST中使用相同的模式,并将额外的属性标记为readOnly。readOnly属性包含在响应中,但不包含在请求中,而writeOnly属性可以在请求中发送,但不包含在响应中。示例:
readOnly
GET
POST
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
如果readOnly或writeOnly属性包含在required列表中,则required仅影响相关范围-仅响应或仅请求。也就是说,只读必需属性仅应用于响应,只写必需属性仅应用于请求。参见文档:文献资料
请注意,我们对负载和响应使用了相同的模型。但是,由于readOnly属性被设置为true,因此id属性被排除在有效负载之外。
true
... Pet: required: - name - photoUrls type: object properties: id: type: integer format: int64 example: 10 readOnly: true ...
2条答案
按热度按时间zbdgwd5y1#
可以使用
allOf
关键字as documented here扩展另一个类型在下面的示例中,
creationType
只有name
属性,但updateType
具有creationType
的所有属性以及id
属性。示例:
gg0vcinb2#
您可以使用
readOnly
关键字来实现这一点,它提供了一种标准化的方法来实现所需的结果。可以使用
readOnly
和writeOnly关键字将特定属性标记为只读或只写。例如,当GET
返回的属性多于POST
中使用的属性时,这很有用-您可以在GET
和POST
中使用相同的模式,并将额外的属性标记为readOnly。readOnly
属性包含在响应中,但不包含在请求中,而writeOnly
属性可以在请求中发送,但不包含在响应中。示例:
如果
readOnly
或writeOnly
属性包含在required列表中,则required仅影响相关范围-仅响应或仅请求。也就是说,只读必需属性仅应用于响应,只写必需属性仅应用于请求。参见文档:文献资料
Petstore示例:
请注意,我们对负载和响应使用了相同的模型。但是,由于
readOnly
属性被设置为true
,因此id
属性被排除在有效负载之外。