首页 文章

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

提问于
浏览 次
0

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

  • 一些在请求中不允许但在响应中显示的只读属性

  • 在请求中允许但未在响应中显示的某些仅限白名的属性和隐藏属性

  • 某些属性仅在/ 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次，我觉得它效率不高 .

所以这是我的问题：

  • 我看到Swagger Spec中有一个鉴别器 . 我应该使用"allOf"这些扩展型号吗？从结果来看，使用不使用此鉴别器，只要"allOf"使用，结果看起来一样 .

  • "readOnly"，如果在基础级别定义，仍会显示在Swagger UI中，在使用或生成文档时需要特殊处理或过滤 . 请求中的演示数据还在Swagger UI请求中显示了这些readOnly属性（但只有模型添加了"read-only"的标签） . 除了我正在尝试之外，还有更好的解决方案 .
    据我所知

  • "white-only"不受支持 . 定义新模型的唯一方法是什么？

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

感谢您的帮助和见解！

swagger swagger-ui swagger-2.0

1 回答

  • 1

    OpenAPI 3.0.x支持writeOnly以及 readOnly 架构属性 . 这应该允许您简化模型， allOf / discriminator 不应该是必要的 .

    回复于

相关问题