我使用https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-2.1&tabs=visual-studio#xml-comments在SwaggerUI中显示了我的班级摘要描述,可以,但没有显示enum
摘要描述!
我的startup.cs
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info
{
Version = "v1",
Title = "My App-Service",
Description = "My Description",
});
c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"));
c.DescribeAllEnumsAsStrings();
});
我的enum
:
public enum GenderEnum
{
/// <summary>
/// Man Description
/// </summary>
Man = 1,
/// <summary>
/// Woman Description
/// </summary>
Woman = 2
}
我想在SwaggerUI中显示Man Description
和Woman Description
像这样:
Man = 1, Man Description
Woman = 2, Woman Description
我正在使用Swashbuckle.AspNetCore v4.0.1
程序包
答案 0 :(得分:0)
不幸的是,OpenAPI规范似乎不支持此功能。有一个开放的Github issue for this。
还有一个开放的Github issue for Swashbuckle。 但是,在此问题中,有一种解决方法可用于创建架构过滤器,该过滤器至少应在枚举类型描述中显示枚举值注释。
答案 1 :(得分:0)
截至 2021 年 6 月,OpenApi 现在支持此功能,您可以扩展 Swagger 以显示详细信息。这是我在 .NET 5.0 上的 C# 代码。
首先在文件中定义架构过滤器(将其命名为 DescribeEnumMembers.cs
并确保将 YourNamespace
更改为您的命名空间的名称):
using System;
using System.Text;
using System.Xml.Linq;
using System.Xml.XPath;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
namespace YourNamespace
{
/// <summary>
/// Swagger schema filter to modify description of enum types so they
/// show the XML docs attached to each member of the enum.
/// </summary>
public class DescribeEnumMembers: ISchemaFilter
{
private readonly XDocument mXmlComments;
/// <summary>
/// Initialize schema filter.
/// </summary>
/// <param name="argXmlComments">Document containing XML docs for enum members.</param>
public DescribeEnumMembers(XDocument argXmlComments)
=> mXmlComments = argXmlComments;
/// <summary>
/// Apply this schema filter.
/// </summary>
/// <param name="argSchema">Target schema object.</param>
/// <param name="argContext">Schema filter context.</param>
public void Apply(OpenApiSchema argSchema, SchemaFilterContext argContext) {
var EnumType = argContext.Type;
if(!EnumType.IsEnum) return;
var sb = new StringBuilder(argSchema.Description);
sb.AppendLine("<p>Possible values:</p>");
sb.AppendLine("<ul>");
foreach(var EnumMemberName in Enum.GetNames(EnumType)) {
var FullEnumMemberName = $"F:{EnumType.FullName}.{EnumMemberName}";
var EnumMemberDescription = mXmlComments.XPathEvaluate(
$"normalize-space(//member[@name = '{FullEnumMemberName}']/summary/text())"
) as string;
if(string.IsNullOrEmpty(EnumMemberDescription)) continue;
sb.AppendLine($"<li><b>{EnumMemberName}</b>: {EnumMemberDescription}</li>");
}
sb.AppendLine("</ul>");
argSchema.Description = sb.ToString();
}
}
}
然后在您的 ASP.NET ConfigureServices()
方法中启用它。这是我剪掉与本练习无关的部分后的代码:
public void ConfigureServices(IServiceCollection argServices) {
// ...<snip other code>
argServices.AddSwaggerGen(SetSwaggerGenOptions);
// ...<snip other code>
return;
// ...<snip other code>
void SetSwaggerGenOptions(SwaggerGenOptions argOptions) {
// ...<snip other code>
AddXmlDocs();
return;
void AddXmlDocs() {
// generate paths for the XML doc files in the assembly's directory.
var XmlDocPaths = Directory.GetFiles(
path: AppDomain.CurrentDomain.BaseDirectory,
searchPattern: "YourAssemblyNameHere*.xml"
);
// load the XML docs for processing.
var XmlDocs = (
from DocPath in XmlDocPaths select XDocument.Load(DocPath)
).ToList();
// ...<snip other code>
// add pre-processed XML docs to Swagger.
foreach(var doc in XmlDocs) {
argOptions.IncludeXmlComments(() => new XPathDocument(doc.CreateReader()), true);
// apply schema filter to add description of enum members.
argOptions.SchemaFilter<DescribeEnumMembers>(doc);
}
}
}
}
记得更改 "YourAssemblyNameHere*.xml"
以匹配您的程序集名称。启用架构过滤器的重要行是:
argOptions.SchemaFilter<DescribeEnumMembers>(doc);
...必须在以下行之后调用:
argOptions.IncludeXmlComments(() => new XPathDocument(doc.CreateReader()), true);
使用上面的代码,如果你有一个像这样定义的枚举类型,例如:
/// <summary>
/// Setting to control when a no-match report is returned when searching.
/// </summary>
public enum NoMatchReportSetting
{
/// <summary>
/// Return no-match report only if the search query has no match.
/// </summary>
IfNoMatch = 0,
/// <summary>
/// Always return no-match report even if the search query has a match.
/// </summary>
Always = 1,
/// <summary>
/// Never return no-match report even if search query has no match.
/// </summary>
No = 99
}
Swagger 文档最终会显示每个枚举成员的描述,作为枚举类型本身的描述的一部分:
答案 2 :(得分:-1)
我使用description属性解决了这个问题。这是一个示例用法:
public enum GenderEnum
{
[Description("Man Description")]
Man = 1,
[Description("Woman Description")]
Woman = 2
}