@达乌德 回答 https://stackoverflow.com/a/60276722/4390133是一部杰作
但它只适用于旧版本Swashbuckle
(不知道是哪个版本)
如果你有Swashbuckle
6.x该代码将NOT编译。
这是相同的解决方案,但适用于Swashbuckle
6.x
using Microsoft.OpenApi.Any;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
/// <summary>
/// Add enum value descriptions to Swagger
/// https://stackoverflow.com/a/49941775/1910735
/// </summary>
public class EnumDocumentFilter : IDocumentFilter
{
/// <inheritdoc />
public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
{
foreach (KeyValuePair<string, OpenApiPathItem> schemaDictionaryItem in swaggerDoc.Paths)
{
OpenApiPathItem schema = schemaDictionaryItem.Value;
foreach (OpenApiParameter property in schema.Parameters)
{
IList<IOpenApiAny> propertyEnums = property.Schema.Enum;
if (propertyEnums.Count > 0)
property.Description += DescribeEnum(propertyEnums);
}
}
if (swaggerDoc.Paths.Count == 0)
return;
// add enum descriptions to input parameters
foreach (OpenApiPathItem pathItem in swaggerDoc.Paths.Values)
{
DescribeEnumParameters(pathItem.Parameters);
foreach (KeyValuePair<OperationType, OpenApiOperation> operation in pathItem.Operations)
DescribeEnumParameters(operation.Value.Parameters);
}
}
private static void DescribeEnumParameters(IList<OpenApiParameter> parameters)
{
if (parameters == null)
return;
foreach (OpenApiParameter param in parameters)
{
if (param.Schema.Enum?.Any() == true)
{
param.Description += DescribeEnum(param.Schema.Enum);
}
else if (param.Extensions.ContainsKey("enum") &&
param.Extensions["enum"] is IList<object> paramEnums &&
paramEnums.Count > 0)
{
param.Description += DescribeEnum(paramEnums);
}
}
}
private static string DescribeEnum(IEnumerable<object> enums)
{
List<string> enumDescriptions = new();
Type? type = null;
foreach (object enumOption in enums)
{
if (type == null)
type = enumOption.GetType();
enumDescriptions.Add($"{Convert.ChangeType(enumOption, type.GetEnumUnderlyingType())} = {Enum.GetName(type, enumOption)}");
}
return Environment.NewLine + string.Join(Environment.NewLine, enumDescriptions);
}
}
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
//https://stackoverflow.com/a/60276722/4390133
public class EnumFilter : ISchemaFilter
{
public void Apply(OpenApiSchema schema, SchemaFilterContext context)
{
if (schema is null)
throw new ArgumentNullException(nameof(schema));
if (context is null)
throw new ArgumentNullException(nameof(context));
if (context.Type.IsEnum is false)
return;
schema.Extensions.Add("x-ms-enum", new EnumFilterOpenApiExtension(context));
}
}
using System.Text.Json;
using Microsoft.OpenApi;
using Microsoft.OpenApi.Interfaces;
using Microsoft.OpenApi.Writers;
using Swashbuckle.AspNetCore.SwaggerGen;
public class EnumFilterOpenApiExtension : IOpenApiExtension
{
private readonly SchemaFilterContext _context;
public EnumFilterOpenApiExtension(SchemaFilterContext context)
{
_context = context;
}
public void Write(IOpenApiWriter writer, OpenApiSpecVersion specVersion)
{
JsonSerializerOptions options = new() { WriteIndented = true };
var obj = new {
name = _context.Type.Name,
modelAsString = false,
values = _context.Type
.GetEnumValues()
.Cast<object>()
.Distinct()
.Select(value => new { value, name = value.ToString() })
.ToArray()
};
writer.WriteRaw(JsonSerializer.Serialize(obj, options));
}
}
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
/// <summary>
/// Adds extra schema details for an enum in the swagger.json i.e. x-enumNames (used by NSwag to generate Enums for C# client)
/// https://github.com/RicoSuter/NSwag/issues/1234
/// </summary>
public class NSwagEnumExtensionSchemaFilter : ISchemaFilter
{
public void Apply(OpenApiSchema schema, SchemaFilterContext context)
{
if (schema is null)
throw new ArgumentNullException(nameof(schema));
if (context is null)
throw new ArgumentNullException(nameof(context));
if (context.Type.IsEnum)
schema.Extensions.Add("x-enumNames", new NSwagEnumOpenApiExtension(context));
}
}
using System.Text.Json;
using Microsoft.OpenApi;
using Microsoft.OpenApi.Interfaces;
using Microsoft.OpenApi.Writers;
using Swashbuckle.AspNetCore.SwaggerGen;
public class NSwagEnumOpenApiExtension : IOpenApiExtension
{
private readonly SchemaFilterContext _context;
public NSwagEnumOpenApiExtension(SchemaFilterContext context)
{
_context = context;
}
public void Write(IOpenApiWriter writer, OpenApiSpecVersion specVersion)
{
string[] enums = Enum.GetNames(_context.Type);
JsonSerializerOptions options = new() { WriteIndented = true };
string value = JsonSerializer.Serialize(enums, options);
writer.WriteRaw(value);
}
}
最后一件事,过滤器的注册
services.AddSwaggerGen(c =>
{
... the rest of your configuration
// REMOVE THIS to use Integers for Enums
// c.DescribeAllEnumsAsStrings();
// add enum generators based on whichever code generators you decide
c.SchemaFilter<NSwagEnumExtensionSchemaFilter>();
c.SchemaFilter<EnumFilter>();
});
NOTES
- 我正在使用 C# 10 功能(隐式使用和其他)如果您不使用 C# 10,那么您必须添加一些 using 语句并恢复到旧的命名空间样式,并为了 C# 进行一些其他小的修改
- 我测试了这段代码,结果与原始答案相同