[英]Swagger C# Enum generation - underlying int values do not match the original enum
我在我的服務器上創建了一個手動設置整數值的枚舉,而不是從 0 開始的默認增量
public enum UserType
{
Anonymous = 0,
Customer = 10,
Technician = 21,
Manager = 25,
Primary = 30
}
我的服務器使用 AspNetCore.App 2.2.0 運行。 它在 Startup.cs 中使用 swashbuckle aspnetcore 4.0.1 進行配置,以在每次啟動服務器時生成一個 swagger json 文件來描述 api。
然后,我使用 NSwag Studio for windows v 13.2.3.0 生成帶有該 swagger JSON 文件的 C sharp api 客戶端,用於 Xamarin 應用程序。 生成的 c sharp api 客戶端中生成的枚舉如下所示 - 基礎整數值與原始枚舉不匹配。
[System.CodeDom.Compiler.GeneratedCode("NJsonSchema", "10.1.5.0 (Newtonsoft.Json v11.0.0.0)")]
public enum UserType
{
[System.Runtime.Serialization.EnumMember(Value = @"Anonymous")]
Anonymous = 0,
[System.Runtime.Serialization.EnumMember(Value = @"Customer")]
Customer = 1,
[System.Runtime.Serialization.EnumMember(Value = @"Technician")]
Technician = 2,
[System.Runtime.Serialization.EnumMember(Value = @"Manager")]
Manager = 3,
[System.Runtime.Serialization.EnumMember(Value = @"Primary")]
Primary = 4,
}
這給我的客戶端帶來了一個問題,因為在某些情況下我需要知道整數值。 我正在尋找一種解決方案,每次我想知道客戶端的整數值時,我都可以避免編寫轉換器。
選項 1:我在 NSwag Studio 或 .net 配置中是否缺少一個選項(我的 Startup.Cs 配置在下面供參考),我可以強制生成的枚舉獲得與原始枚舉相同的整數值?
選項 2:或者,如果沒有,我的客戶端和我的服務器都可以通過共享類庫訪問相同的原始枚舉。 有沒有辦法讓生成的 api 客戶端使用 apiclient.cs 中的實際原始枚舉而不是生成自己的?
參考:
我在 Startup.Cs 中的招搖生成代碼的枚舉部分看起來像這樣
services.AddJsonOptions(options =>
{
options.SerializerSettings.Converters.Add(new StringEnumConverter());
....
services.AddSwaggerGen(setup =>
{
setup.SwaggerDoc("v1", new Info { Title = AppConst.SwaggerTitle, Version = "v1" });
setup.UseReferencedDefinitionsForEnums();
... other stuff...
}
@Dawood 答案是傑作
但它僅適用於舊版本的Swashbuckle
(我不確定哪些版本)
如果您有Swashbuckle
6.x ,則該代碼將無法編譯。
這是相同的解決方案,但適用於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>();
});
筆記
所以這些是我正在使用的兩個枚舉助手。 一個由 NSwag ( x-enumNames
) 使用,另一個由 Azure AutoRest ( x-ms-enums
) 使用
終於找到了EnumDocumentFilter
的參考( https://stackoverflow.com/a/49941775/1910735 )
using System;
using System.Collections.Generic;
using System.Linq;
using System.Reflection;
using Swashbuckle.AspNetCore.Swagger;
using Swashbuckle.AspNetCore.SwaggerGen;
namespace SwaggerDocsHelpers
{
/// <summary>
/// Add enum value descriptions to Swagger
/// https://stackoverflow.com/a/49941775/1910735
/// </summary>
public class EnumDocumentFilter : IDocumentFilter
{
/// <inheritdoc />
public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
{
// add enum descriptions to result models
foreach (var schemaDictionaryItem in swaggerDoc.Definitions)
{
var schema = schemaDictionaryItem.Value;
foreach (var propertyDictionaryItem in schema.Properties)
{
var property = propertyDictionaryItem.Value;
var propertyEnums = property.Enum;
if (propertyEnums != null && propertyEnums.Count > 0)
{
property.Description += DescribeEnum(propertyEnums);
}
}
}
if (swaggerDoc.Paths.Count <= 0) return;
// add enum descriptions to input parameters
foreach (var pathItem in swaggerDoc.Paths.Values)
{
DescribeEnumParameters(pathItem.Parameters);
// head, patch, options, delete left out
var possibleParameterisedOperations = new List<Operation> { pathItem.Get, pathItem.Post, pathItem.Put };
possibleParameterisedOperations.FindAll(x => x != null)
.ForEach(x => DescribeEnumParameters(x.Parameters));
}
}
private static void DescribeEnumParameters(IList<IParameter> parameters)
{
if (parameters == null) return;
foreach (var param in parameters)
{
if (param is NonBodyParameter nbParam && nbParam.Enum?.Any() == true)
{
param.Description += DescribeEnum(nbParam.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)
{
var enumDescriptions = new List<string>();
Type type = null;
foreach (var 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)}";
}
}
public class EnumFilter : ISchemaFilter
{
public void Apply(Schema model, SchemaFilterContext context)
{
if (model == null)
throw new ArgumentNullException("model");
if (context == null)
throw new ArgumentNullException("context");
if (context.SystemType.IsEnum)
{
var enumUnderlyingType = context.SystemType.GetEnumUnderlyingType();
model.Extensions.Add("x-ms-enum", new
{
name = context.SystemType.Name,
modelAsString = false,
values = context.SystemType
.GetEnumValues()
.Cast<object>()
.Distinct()
.Select(value =>
{
//var t = context.SystemType;
//var convereted = Convert.ChangeType(value, enumUnderlyingType);
//return new { value = convereted, name = value.ToString() };
return new { value = value, name = value.ToString() };
})
.ToArray()
});
}
}
}
/// <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(Schema model, SchemaFilterContext context)
{
if (model == null)
throw new ArgumentNullException("model");
if (context == null)
throw new ArgumentNullException("context");
if (context.SystemType.IsEnum)
{
var names = Enum.GetNames(context.SystemType);
model.Extensions.Add("x-enumNames", names);
}
}
}
}
然后在你的 startup.cs 中配置它們
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>();
});
這應該在 Swagger.json 文件中生成您的枚舉
sensorType: {
format: "int32",
enum: [
0,
1,
2,
3
],
type: "integer",
x-enumNames: [
"NotSpecified",
"Temperature",
"Fuel",
"Axle"
],
x-ms-enum: {
name: "SensorTypesEnum",
modelAsString: false,
values: [{
value: 0,
name: "NotSpecified"
},
{
value: 1,
name: "Temperature"
},
{
value: 2,
name: "Fuel"
},
{
value: 3,
name: "Axle"
}
]
}
},
但是,此解決方案存在一個問題(我沒有時間研究)是枚舉名稱是使用我在 NSwag 中的 DTO 名稱生成的 - 如果您確實找到了解決方案,請告訴我 :-)
例如,以下枚舉是使用 NSwag 生成的:
更新
dawood在上面發布了一個工作解決方案,它完全符合我的要求。
原始答案
目前似乎沒有辦法做到這一點。 正如@sellotape 在他的評論中提到的,這甚至可能不是一個好主意。 由於我控制着服務器並且它是一個相對較新的項目,我已將我的枚舉重構為正常的“從零開始的順序”樣式。
我確實認為它對某些用例很有用——例如,支持不能輕易重構的遺留枚舉,或者能夠對中間有間隙的枚舉進行編號,例如 10、20、30。 這將允許稍后插入 11,12 等,同時保留將某種“順序”編碼到您的枚舉的能力,並且不會隨着項目的增長而破壞該順序。
然而,目前這似乎不可能,所以我們將繼續這樣做。
聲明:本站的技術帖子網頁,遵循CC BY-SA 4.0協議,如果您需要轉載,請注明本站網址或者原文地址。任何問題請咨詢:yoyou2525@163.com.