ASP.NET Core Web API：如何在Swagger文档中标记必填字段

问题描述 #

在ASP.NET Core 6 Web API中配置Swagger后，Swagger页面未显示接口的必填字段，现有配置代码如下：

SwaggerDocOptions 类 #

public class SwaggerDocOptions
{
    public string Title { get; set; }
    public string Description { get; set; }
    public string Organization { get; set; }
    public string Email { get; set; }
}

Program.cs 配置代码 #

builder.Services.AddSwaggerGen();
builder.Services.AddOptions<SwaggerGenOptions>()
    .Configure<IApiVersionDescriptionProvider>((swagger, service) =>
    {
        foreach (ApiVersionDescription description in service.ApiVersionDescriptions)
        {
            swagger.SwaggerDoc(description.GroupName, new OpenApiInfo
            {
                Title = swaggerDocOptions.Title,
                Version = description.ApiVersion.ToString(),
                Description = swaggerDocOptions.Description,
                TermsOfService = new Uri("mysite.org/LICENSE.md"),
                Contact = new OpenApiContact
                {
                    Name = swaggerDocOptions.Organization,
                    Email = swaggerDocOptions.Email
                },
                License = new OpenApiLicense
                {
                    Name = "MIT",
                    Url = new Uri("mysite.org/MyApp")
                }
            });
        }

        var security = new Dictionary<string, IEnumerable<string>>
        {
            {"Bearer", new string[0]}
        };

        swagger.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
        {
            Description = "JWT Authorization header using the Bearer scheme.",
            Name = "Authorization",
            In = ParameterLocation.Header,
            Type = SecuritySchemeType.ApiKey,
            Scheme = "Bearer",
            BearerFormat = "JWT"
        });

        swagger.OperationFilter<AuthorizeCheckOperationFilter>();

        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        swagger.IncludeXmlComments(xmlPath);

    });
// Register and Configure API versioning
builder.Services.AddApiVersioning(options =>
{
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ReportApiVersions = true;
});

// Register and configure API versioning explorer
builder.Services.AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;

});


// Configure the HTTP request pipeline.
app.UseSwagger();
app.UseSwaggerUI();

解决方案 #

1. 为模型属性添加必填特性 #

确保请求/响应模型中的必填字段标记[Required]特性（来自System.ComponentModel.DataAnnotations命名空间），示例：

public class CreateProductRequest
{
    [Required]
    public string Name { get; set; }

    [Required]
    public decimal Price { get; set; }

    public string Description { get; set; } // 非必填字段
}

2. 启用Swagger的数据注解支持 #

在AddSwaggerGen配置中添加EnableAnnotations()方法，让Swagger识别数据注解规则：
修改Program.cs的Swagger配置段，在IncludeXmlComments之后追加：

swagger.EnableAnnotations();

3. 确保XML注释生成配置正确（可选） #

若需要在Swagger中显示字段描述信息，需确认项目已启用XML文档生成：

• 右键项目 → 属性 → 生成 → 勾选"XML文档文件"，保留默认输出路径即可。
• 确保IncludeXmlComments方法引用的路径能正确找到生成的XML文件。

4. 适配FluentValidation（若使用） #

如果项目用FluentValidation替代数据注解，需安装FluentValidation.AspNetCore包，并添加Swagger集成：

// 先安装NuGet包：FluentValidation.AspNetCore
builder.Services.AddFluentValidationAutoValidation();
builder.Services.AddFluentValidationClientsideAdapters();

// 在Swagger配置中添加过滤器
swagger.OperationFilter<FluentValidationOperationFilter>();

5. 完善SwaggerUI配置 #

确保UseSwaggerUI正确加载各版本的Swagger文档，示例：

// 需先注入IApiVersionDescriptionProvider
var apiVersionDescriptionProvider = app.Services.GetRequiredService<IApiVersionDescriptionProvider>();

app.UseSwaggerUI(options =>
{
    foreach (var description in apiVersionDescriptionProvider.ApiVersionDescriptions)
    {
        options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
    }
});

完成以上配置后重启应用，Swagger页面会在必填字段旁标注*，并在请求示例中明确提示必填项。

内容的提问来源于stack exchange，提问作者Ayobamilaye