在Swagger文件中重载描述（YAML）

Question

我在编写swagger文件时遇到问题。当我描述一个参数时，描述会被这个相同参数的$ 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

结果： the description is overloaded

有人可以帮我解决这个问题吗？

Answer 1

$ref会覆盖其所有兄弟属性 - 这就是$ref的工作原理。您可以尝试使用以下方法解决此问题：

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

这将在Swagger Editor和Swagger UI中使用。

OpenAPI规范存储库中还有一个feature request，用于提供将$ref与其他属性组合的更好方法。