SwaggerUI不显示枚举摘要描述,C#.net核心?

时间:2018-11-13 13:32:20

标签: c# enums .net-core asp.net-core-webapi swagger-ui

我使用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
}

它显示如下内容:
Swagger UI enum

我想在SwaggerUI中显示Man DescriptionWoman Description
像这样:

Man = 1, Man Description
Woman = 2,  Woman Description


我正在使用Swashbuckle.AspNetCore v4.0.1程序包

3 个答案:

答案 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 文档最终会显示每个枚举成员的描述,作为枚举类型本身的描述的一部分:

swagger doc screenshot

答案 2 :(得分:-1)

我使用description属性解决了这个问题。这是一个示例用法:

public enum GenderEnum
{
    [Description("Man Description")]
    Man = 1,

    [Description("Woman Description")]
    Woman = 2
}