英文:
How to change the example value for an enum property in the Swagger UI?
问题
I'm using AddSwaggerGen in an ASP.NET Core project. I wrote an ISchemaFilter to change the property values that the Swagger UI uses in its example JSON. I used this approach because the filter instantiates my model types to get the default values for the properties. That part works and isn't shown here.
The filter also changes the example value for Nullable<T> properties to null. This works for most types, but fails for enum properties.
public class SwaggerPropertyValueFilter : ISchemaFilter
{
public void Apply(OpenApiSchema schema, SchemaFilterContext context)
{
if (context.Type.Namespace == "MyAPI.Services.Models" && context.Type.GetConstructor(Type.EmptyTypes) != null)
{
var schemaProps = schema.Properties.OrderBy(o => o.Key).Select(o => o.Value);
var modelProps = context.Type.GetProperties().OrderBy(o => o.Name);
var props = schemaProps.Zip(modelProps, (schema, model) => new { Schema = schema, Model = model } );
foreach(var prop in props)
{
var type = Nullable.GetUnderlyingType(prop.Model.PropertyType);
if (type != null)
{
prop.Schema.Example = new OpenApiNull();
continue;
}
}
}
}
}
I noticed that OpenApiSchema.Nullable is false for nullable enum properties, but setting it to true also doesn't make any difference.
英文:
I'm using AddSwaggerGen in an ASP.NET Core project. I wrote an ISchemaFilter to change the property values that the Swagger UI uses in its example JSON. I used this approach because the filter instantiates my model types to get the default values for the properties. That part works and isn't shown here.
The filter also changes the example value for Nullable<T> properties to null. This works for most types, but fails for enum properties.
public class SwaggerPropertyValueFilter : ISchemaFilter
{
public void Apply(OpenApiSchema schema, SchemaFilterContext context)
{
if (context.Type.Namespace == "MyAPI.Services.Models" && context.Type.GetConstructor(Type.EmptyTypes) != null)
{
var schemaProps = schema.Properties.OrderBy(o => o.Key).Select(o => o.Value);
var modelProps = context.Type.GetProperties().OrderBy(o => o.Name);
var props = schemaProps.Zip(modelProps, (schema, model) => new { Schema = schema, Model = model } );
foreach(var prop in props)
{
var type = Nullable.GetUnderlyingType(prop.Model.PropertyType);
if (type != null)
{
prop.Schema.Example = new OpenApiNull();
continue;
}
}
}
}
}
I noticed that OpenApiSchema.Nullable is false for nullable enum properties, but setting it to true also doesn't make any difference.
答案1
得分: -1
这是由于在OpenAPI架构中将枚举视为引用类型引起的。（顺便说一下，字符串不是引用类型。）有两个选项/解决方法：
- 调用
SwaggerGenOptions.UseAllOfToExtendReferenceSchemas()以使Swagger UI允许在引用类型的属性上包含元数据。使用此选项时，架构过滤器的Apply有时会使用具有属性的context.Type和没有属性的OpenApiSchema，因此您需要进行检查。 - 调用
SwaggerGenOptions.UseInlineDefinitionsForEnums()以内联枚举属性。使用此选项后，枚举不再是架构中的一种类型。
英文:
This is caused by enums being treated as reference types in the OpenAPI schema. (Incidentally, strings aren't.) There are two options/workarounds:
- Call
SwaggerGenOptions.UseAllOfToExtendReferenceSchemas()to make the Swagger UI allow metadata on properties of reference types. With this option, the schema filter'sApplyis sometimes called with acontext.Typethat has properties and anOpenApiSchemathat does not, so you have to check for that. - Call
SwaggerGenOptions.UseInlineDefinitionsForEnums()to inline enum properties. With this option, the enum is no longer a type in your schema.
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库，让每个人都能够通过互相帮助和分享经验来进步。
评论