Swagger：使用 ref 添加描述

Question

我想为引用他的定义的对象属性添加描述。类似的东西：

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

但是编辑器警告description属性会被跳过：

Extra JSON Reference properties will be ignored: description

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

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

您如何在 Swaggers 规范中做到这一点？

感谢您的帮助！

Answer 1

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

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

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

Answer 2

虽然它不符合 JSON 标准。 如果你正在使用 Swashbuckle 来产生你的招摇。 我利用了模式的“扩展”属性。 并设法创建了一个带有 $ref 和扩展属性的大张旗鼓的 JSON。

var refSchema = new OpenApiSchema
{      
     //Reference = new OpenApiReference { ExternalResource = referenceLink, Type = ReferenceType.Link }, this wont work and omit all your other properties
    Extensions = new Dictionary<string, IOpenApiExtension>
    {
        { "$ref" , new OpenApiString(referenceLink) } // adding ref as extension cause according to JSON standards $ref shouldnt have any other properties
    },
    Description = prop.Value.Description,
    ReadOnly = prop.Value.ReadOnly,
    Required = prop.Value.Required,
    Type = prop.Value.Type,
    Example = prop.Value.Example,
};

Answer 3

您可以简单地将description 属性移动到PhoneNumber 的定义中。您的原始帖子未显示您如何定义 PhoneNumber，但此 sn-p 验证时没有警告：

definitions:
  phoneNumber:
    type: string
    description: Phone number of the card holder

  newCreditCard:
    type: object
    properties:
      billingPhone:
        $ref: "#/definitions/phoneNumber"

如果此答案不是您想要的，请重述问题。我们需要知道你想要完成什么。