使用不同的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不是必需的。