使用不同的Swagger Models属性进行收集/详细请求/响应

Question

我是Swagger的初学者，我正在尝试定义具有以下内容的端点：

• 请求中不允许但在响应中显示的一些只读属性
• 在请求中允许但未在响应中显示的某些仅限白名的属性和隐藏
• 某些属性仅在/ resources的集合级别上，但在/ resources / resource-id
上有一些其他附加详细信息

我正在做的是定义以下模型：

• ResourceBaseModel：这会保存所有
的所有共享属性

ResourceBaseModel:
  type: object
  properties:
    shared_properties:
      type: string

• ResourceCollectionResponse：这是包装响应附加属性

ResourceCollectionResponse:
  type: array
  items:
    type: object
    allOf: 
      - $ref: ResourceBaseModel
      - type: object
        properties:
          collection_normal_properties:
            type: string
          collection_read_only_properties:
            type: string
            readOnly: true

• ResourceDetailResponse：这是为响应添加不同的属性

ResourceDetailResponse:
  type: object
  allOf: 
    - $ref: ResourceBaseModel
    - type: object
      properties:
        detail_normal_properties:
          type: string
        detail_read_only_properties:
          type: string
          readOnly: true

• ResourceRequest：同样，添加其他和只写属性

ResourceRequest:
  type: object
  allOf: 
    - $ref: ResourceBaseModel
    - type: object
      properties:
        request_write_only_properties:
          type: string

这使得每个模型定义了4次，我觉得效率不高。

所以这是我的问题：

1. 我看到Swagger Spec中有一个鉴别器。我应该使用这些扩展型号的“allOf”吗？从结果来看，使用不使用此鉴别器，只要使用“allOf”，结果看起来就一样。
2. “readOnly”，如果在基本级别定义，仍会显示在Swagger UI中，在使用或生成文档时需要特殊处理或过滤。请求中的演示数据还在Swagger UI请求中显示这些readOnly属性（但只有模型添加了“只读”标签）。除了我正在尝试之外，还有更好的解决方案。
3. 据我所知，“仅白色”不受支持。定义新模型是唯一的方法吗？

我想知道是否有一天我只能定义一个模型来描述所有模型，或者您认为可以编译为Swagger YAML的创新语言能够使整个社区受益吗？就像Sass / LESS如何构建CSS一样？

感谢您的帮助和见解！

Answer 1

OpenAPI 3.0.x支持writeOnly以及readOnly架构属性。这可以让您简化模型，allOf / discriminator不是必需的。