Can't generate enum item descriptions

[Mazas17]

According to OpenAPI documentation, it is possible to add description to single enum item:

      parameters:
        - in: query
          name: sort
          schema:
            type: string
            enum: [asc, desc]
          description: >
            Sort order:
             * `asc` - Ascending, from A to Z
             * `desc` - Descending, from Z to A

https://swagger.io/docs/specification/data-models/enums/

How to do that with swashbuckle? Can't find any documentation

[cadmaticpgustafsson]

This would be a nice feature. I found this article which describes how you can do it manually, not sure if this works with the latest version. I have not tried.

[jgarciadelanoceda]

Right now if you combine that with a DocumentFilter you will have everything.

public class EnumDocumentFilter : IDocumentFilter
{
	public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
	{
		foreach (var path in swaggerDoc.Paths.Values)
		{
			foreach (var operation in path.Operations.Values)
			{
				foreach (var parameter in operation.Parameters)
				{
					var schematypeId = parameter.Schema.Reference?.Id;

					if (!string.IsNullOrEmpty(schematypeId) && context.SchemaRepository.Schemas.TryGetValue(schematypeId, out var schema))
					{
						if ((schema.Enum?.Count ?? 0) > 0)
						{
							parameter.Description = schema.Description;
						}
					}
					if (!string.IsNullOrWhiteSpace(parameter.Schema.Description))
					{
						parameter.Description = parameter.Schema.Description;
					}
				}
			}
		}
	}
}

The SchemaFilter:

public class EnumSchemaFilter : ISchemaFilter
{
	public void Apply(OpenApiSchema schema, SchemaFilterContext context)
	{
		bool isEnumArgument = (context.Type?.GenericTypeArguments?.Length ?? 0) == 1 && context.Type.GenericTypeArguments.All(b => b.IsEnum);
		var isEnumArray = context.Type.IsArray && context.Type.GetElementType().IsEnum;
		if (context.Type.IsEnum || isEnumArgument || isEnumArray)
		{
			Type enumType = (context.Type.IsEnum, isEnumArgument, isEnumArray) switch
			{
				(true, _, _) => context.Type,
				(_, true, _) => context.Type.GenericTypeArguments.First(),
				_ => context.Type.GetElementType()
			};

			StringBuilder stringBuilder = new("<p>Members:</p><ul>");
			OpenApiArray names = [];
			foreach (var enumValue in Enum.GetValues(enumType))
			{
				if (enumValue is Enum value)
				{
					names.Add(new OpenApiString(value.ToString()));
					stringBuilder.Append($"<li>{value} - {value:d}</li>");
				}
			}
			schema.Extensions.Add("x-enum-varnames", names);
			schema.Description = stringBuilder.Append("</ul>").ToString();
		}
	}
}

I will investigate if it's interesting insert this into the library

[jgarciadelanoceda]

The IDocumentFilter could be replaced by a IParameterFilter that it's much simpler:

public class ParameterFilter : IParameterFilter
{
	public void Apply(OpenApiParameter parameter, ParameterFilterContext context)
	{
		if (string.IsNullOrWhiteSpace(parameter.Description))
		{
			parameter.Description = parameter.Schema.Description;
			if (string.IsNullOrEmpty(parameter.Description)
				&& !string.IsNullOrEmpty(parameter.Schema?.Reference?.Id)
				&& context.SchemaRepository.Schemas.TryGetValue(parameter.Schema.Reference.Id, out var value))
			{
				parameter.Description = value.Description;
			}
		}
	}
}

I am trying to see if I can add this copy of information from the Schema into the library