Swagger:使用 ref 添加描述 [英] Swagger: Add description with ref

问题描述

我想向引用其定义的对象属性添加描述.类似的东西:

I want to add a description to an object property that his definition is referenced. Something like that:

      newCreditCard:
        type: object
        properties:
          billingPhone:
            description: Phone number of the card holder
            $ref: "#/definitions/PhoneNumber"

但编辑器警告将跳过描述属性:

But the editor warns that the description property will be skipped:

Extra JSON Reference properties will be ignored: description

我发现了一个不太优雅的解决方法，它适用于编辑器，但不适用于 Swagger UI(不确定这可能是由于最近更新到 3.0.2 版本的 Swagger UI)

I have found a less elegant workaround that works for the editor, but not for the Swagger UI (not sure that is may due to the recent update to 3.0.2 version of the Swagger UI)

      newCreditCard:
        type: object
        properties:
          billingPhone:
            description: Phone number of the card holder
            allOf:
            - $ref: "#/definitions/PhoneNumber"

你是如何在 Swaggers 规范中做到这一点的?

How do you do it in your Swaggers specification?

感谢您的帮助！

推荐答案

如果您在 $ref 的同一级别添加任何内容，它将被忽略.

If you add anything to the same level of $ref it will be ignored .

json $ref 定义 https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03#section-3

json $ref definition https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03#section-3

正确的方法是在引用的对象中提供描述.

correct way is to provide the description in the referenced object.

这篇关于Swagger:使用 ref 添加描述的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！