如何在同一对象的开放API请求和响应中具有不同的必填字段？

Question

我使用的是openapi 3.0.3版本，我们有scanario，我们不想让一个字段强制响应。下面是开放Api模式Snippit的示例。

例如，这里是MerchantDetails对象，其中“merchantName”和“merchantId”是必填字段。

MerchantDetails:
  description: Used to pass merchant specific data during the transaction.
  properties:
    merchantName:
      type: string
      maxLength: 64
    merchantId:
      type: string
      maxLength: 16
  required:
    - merchantName
    - merchantId

作为回应，我们使用相同的对象，但我们只希望根据需要保留一个字段“merchantId”。有没有办法在不创建新对象的情况下实现这一点？

MerchantDetails:
  description: Used to pass merchant specific data during the transaction.
  properties:
    merchantName:
      type: string
      maxLength: 64
    merchantId:
      type: string
      maxLength: 16
  required:
    - merchantId

Answer 1

您可以使用只读和写式关键字将特定属性标记为仅在响应中或仅在请求中。

如果“必需”列表中包含只读或写式属性，则必需仅影响相关范围–仅响应或仅请求。也就是说，只读必需属性仅适用于响应，而只写必需属性–仅适用于请求。

不确定是否所有工具都支持这些关键字。我已经测试过Redoc可以正确生成文档。

MerchantDetails:
  description: Used to pass merchant specific data during the transaction.
  properties:
    merchantName: 
      type: string
      maxLength: 64
      writeOnly: true  # only in request
    merchantId:
      type: string
      maxLength: 16
  required:
    - merchantName
    - merchantId

请阅读https://swagger.io/docs/specification/data-models/data-types/中的只读和只写属性部分