如果您将任何内容添加到$ref的同一级别，它将被忽略。
json $引用https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03#section-3
正确的方法是在被引用对象中提供描述。

您可以简单地将description属性移到PhoneNumber的定义中。您的原始帖子没有显示您是如何定义PhoneNumber的，但是下面的代码片段验证了此代码，没有警告：

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

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

如果这个答案不是你想要的，请重新回答问题。我们需要知道你想要达到什么目的。

虽然它不符合JSON标准。如果您使用Swashbuckle生成swagger，我利用schema的“Extensions”属性，并设法创建了一个swagger JSON，它具有$ref和扩展属性。

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,
};

对于将Swashbuckle与ASP.NET一起使用的任何人，您可以使用以下代码将$ref构造置于allOf之下（就像：

// do this wherever you are calling AddSwaggerGen()
ArgBuilder.Services.AddSwaggerGen(opts => {
  opts.UseAllOfToExtendReferenceSchemas(); // add this line.
});

现在，如果您有一个模型，其中有两个相同类型的属性，则每个字段的单独描述将显示在Swagger UI中（例如，下面的FooHeader和BarHeader都是HttpHeader类型的属性，它们的描述将显示）：