c# - 将描述中的链接添加到 Swagger 中的其他操作(通过 Swashbuckle)

Question

根据documentation for Swashbuckle , 最新版本只支持少数 XML 注释。好像是 <example> 这样的 XML 注释或 <see>当前不支持 but will be implemented in Swashbuckle v6 .

在那之前，有没有我可以做的解决方法来模仿 <example> 的行为？或 <see> ？

我想以某种方式在 <see> 中添加一个链接(使用带有 cref 的 <summary>)在端点模型下列出的枚举，指向枚举的相应端点(Swagger 中的一个不同的端点，它获取该枚举的类型列表)。

编辑(不确定如何在评论中格式化):

我想让 Swagger 检测 <see>并在枚举的描述中显示指向不同端点的链接

/// <summary>
/// Generic description. 
/// Find enum types <see cref="ContactEntityType">here</see>
/// </summary>
[PropertyRequired, PropertyStringAsEnum(typeof(ContactEntityType))]
[DataMember(Name = "entityType")]
public NamedReference EntityType { get; set; }

Answer 1

2022最新版swagger支持参数注释

/// <param name="MyParamaterName" example="123"> Should be defined as model MyModelName</param>
[HttpPost]
[Route("SomeWebApiFunction")]
public async Task<bool> SomeWebApiFunction(MyModelName MyParamaterName)
{
    return true;
}

public class MyModelName
{
    public string PropName { get; set; }
}

Swaggers 非常擅长给每个部分一个唯一的 id，你可以用 inspect 元素检查每个部分的 id 属性。这使得围绕文档进行链接变得非常容易。例如，我们可以添加一个链接以滚动到 MyModelName 描述；

/// <param name="MyParamaterName" example="123"> Should be defined as model <a href='#model-MyModelName'>MyModelName</a></param>

不要忘记IncludeXmlComments

builder.Services.AddSwaggerGen(c => {
    string fileName = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var filePath = Path.Combine(AppContext.BaseDirectory, fileName);
    c.IncludeXmlComments(filePath);
});

如果您使用的是 Visual Studio，请确保已启用“生成 XML 注释”。

如果您使用的是 Asp.net Core 并且未生成 xml，则必须在 .csproj 文件的 PropertyGroup 中添加以下行。

<PropertyGroup>  
<DocumentationFile>bin\$(Configuration)\$(TargetFramework)\YourApplicationNameGoesHere.xml</DocumentationFile>
</PropertyGroup>

将 YourApplicationNameGoesHere 替换为您的应用程序名称。如果由于某种原因您不知道 xml 文件名，您可以在项目构建的输出文件夹中找到它。