如何在Swagger文档中显示<remarks>
如何在Swagger文档中显示<remarks>
提问于 2020-02-28 07:43:17
我正在将文档添加到API模型(.Net Framework4.7.2)中。
我通常用这样的词：
''' <summary>
''' My summary
''' </summary>
''' <remarks>My remarks...</remarks>
Public Property MyProperty() As SomeClass当我访问Swagger文档模型时，我看到：
MyProperty (SomeClass)：我的总结
我应该怎么做才能看到“我的评论”(也许当我在文本上徘徊时，如果不是在总结之后)？
谢谢
回答 1
Stack Overflow用户
发布于 2022-07-20 20:15:23
当前，只为控制器操作显示<remarks>，而不显示参数。
请参阅[特性请求]向参数添加备注.问题#1937 .domaindrivendev/Swashackle.AspNetCore
..。Swagger/OpenAPI参数对象只支持输入描述性文本的单个描述字段。为了简单起见，我希望在XML注释标记和Swagger/OpenAPI字段之间保持1:1的映射，而不是将多个标记组合/格式化到一个字段中。所以，你的要求在这一点上不是我打算加给某人的。
但我发现它可以添加自定义IParameterFilter
/// <summary>
/// Add the content of <remarks> to the description of a parameter
/// Inspired by <see cref="Swashbuckle.AspNetCore.SwaggerGen.XmlCommentsParameterFilter"/>
/// </summary>
public class AddRemarksToParameterDescription : IParameterFilter
{
private readonly XPathNavigator _xmlNavigator;
public AddRemarksToParameterDescription(XPathDocument xmlDoc)
{
_xmlNavigator = xmlDoc.CreateNavigator()!;
}
public void Apply(OpenApiParameter parameter, ParameterFilterContext context)
{
if (context.PropertyInfo != null)
{
ApplyPropertyTags(parameter, context);
}
else if (context.ParameterInfo != null)
{
ApplyParamTags(parameter, context);
}
}
private void ApplyPropertyTags(OpenApiParameter parameter, ParameterFilterContext context)
{
var propertyMemberName = XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(context.PropertyInfo);
var propertyNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{propertyMemberName}']");
if (propertyNode == null) return;
var remarksNode = propertyNode.SelectSingleNode("remarks");
if (remarksNode != null)
{
parameter.Description += FormatRemarks(remarksNode.InnerXml);
}
}
private void ApplyParamTags(OpenApiParameter parameter, ParameterFilterContext context)
{
if (!(context.ParameterInfo.Member is MethodInfo methodInfo)) return;
// If method is from a constructed generic type, look for comments from the generic type method
var targetMethod = methodInfo.DeclaringType is { IsConstructedGenericType: true }
? methodInfo.GetUnderlyingGenericTypeMethod()
: methodInfo;
if (targetMethod == null) return;
var methodMemberName = XmlCommentsNodeNameHelper.GetMemberNameForMethod(targetMethod);
var paramNode = _xmlNavigator.SelectSingleNode(
$"/doc/members/member[@name='{methodMemberName}']/param[@name='{context.ParameterInfo.Name}']");
if (paramNode != null)
{
var remarksNode = paramNode.SelectSingleNode("remarks");
if (remarksNode != null)
{
parameter.Description += FormatRemarks(remarksNode.InnerXml);
}
}
}
private static string FormatRemarks(string text)
{
return "<br><br>Remarks: <br><i>" + XmlCommentsTextHelper.Humanize(text) + "</i>";
}
}添加您的设置：
而不是这个：(来自官方自述)
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1",
new OpenApiInfo
{
Title = "My API - V1",
Version = "v1"
}
);
var filePath = Path.Combine(System.AppContext.BaseDirectory, "MyApi.xml");
c.IncludeXmlComments(filePath);
});这样做：
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1",
new OpenApiInfo
{
Title = "My API - V1",
Version = "v1"
}
);
var filePath = Path.Combine(System.AppContext.BaseDirectory, "MyApi.xml");
// ==== NEW
var xmlDox = new XPathDocument(filePath); // Re-use XPathDocument
c.IncludeXmlComments(() => xmlDox); // IncludeXmlComments with current XPathDocument
c.ParameterFilter<AddRemarksToParameterDescription>(xmlDox); // The new filter
});用Swashbuckle.AspNetCore 5.5 + C# 8进行可空分析。我认为它也应该与Swashbuckle.AspNetCore 6一起工作。
页面原文内容由Stack Overflow提供。腾讯云小微IT领域专用引擎提供翻译支持
原文链接：
https://stackoverflow.com/questions/60447302
复制相关文章
相似问题
腾讯云开发者
