Swagger文件（YAML）中的重载描述[重复]

Question

我在写我的招摇文件时遇到了问题。当我描述一个参数时，这个参数的$ref的描述重载了这个描述（参见下面的示例）。

a-body:
    description: The body
    type: object
    properties:
      my_param:
        description: Full description 
        $ref: '#/definitions/reference'

definitions:
    reference:
        type: object
        required: [req]
        description: an http reference
        properties:
          req:
            type: string

结果：描述过载

谁能帮我渡过难关吗？

Answer 1

$ref覆盖其所有同级属性，$ref就是这样工作的。您可以尝试使用以下方法解决此问题：

my_param:
  description: Full description 
  allOf:
    - $ref: '#/definitions/reference'

这将在Swagger编辑器和Swagger UI中工作。

OpenAPI规范存储库中还有一个功能请求，可以提供更好的方式将$ref与其他属性结合起来。