.NET中通过XML注释为Swashbuckle设置格式标识的方法

针对你的场景（.NET 7 + Swashbuckle v6.4.0），Swashbuckle默认不识别XML注释里的<format>标签，需要通过自定义SchemaFilter来解析该标签并同步到OpenAPI Schema中，具体步骤如下：

1. 确保XML注释已启用 #

首先确认项目已开启XML文档生成：

• 右键项目 → 属性 → 生成 → 勾选「XML文档文件」，设置生成路径（例如$(SolutionDir)\$(MSBuildProjectName).xml）

2. 自定义SchemaFilter解析标签 #

创建一个XmlFormatSchemaFilter类，负责读取XML注释中的<format>内容，并将其赋值给OpenAPI Schema的Format字段（同时可追加到描述中）：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Xml.Linq;

public class XmlFormatSchemaFilter : ISchemaFilter
{
    private readonly XDocument _xmlDocument;

    public XmlFormatSchemaFilter(string xmlFilePath)
    {
        _xmlDocument = XDocument.Load(xmlFilePath);
    }

    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 构造XML注释中属性的标识路径（格式：P:命名空间.类名.属性名）
        var memberFullPath = $"P:{context.MemberInfo.DeclaringType?.FullName}.{context.MemberInfo.Name}";
        var targetMember = _xmlDocument.Descendants("member")
            .FirstOrDefault(m => m.Attribute("name")?.Value == memberFullPath);

        if (targetMember == null) return;

        // 提取<format>标签内容
        var formatElement = targetMember.Element("format");
        if (formatElement == null || string.IsNullOrWhiteSpace(formatElement.Value)) return;

        // 设置Schema的Format字段，Swagger UI会自动展示该格式
        schema.Format = formatElement.Value;

        // 可选：将格式信息追加到属性描述中
        var formatDesc = $"格式：{formatElement.Value}";
        schema.Description = string.IsNullOrEmpty(schema.Description) 
            ? formatDesc 
            : $"{schema.Description}<br/>{formatDesc}";
    }
}

3. 注册SchemaFilter到Swagger配置 #

在Program.cs中更新Swagger注册逻辑，添加自定义的SchemaFilter：

builder.Services.AddSwaggerGen(c =>
{
    // 加载XML注释文件
    var xmlFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
    c.IncludeXmlComments(xmlFilePath);

    // 注册自定义SchemaFilter，传入XML文件路径
    c.SchemaFilter<XmlFormatSchemaFilter>(xmlFilePath);
});

4. 保持视图模型的XML注释写法 #

你的视图模型代码无需修改，继续使用<format>标签即可：

public class MeasurementViewModel {
    /// <example>20.01.2003</example>
    /// <format>dd.mm.yyyy</format>
    [JsonProperty("patient_birthdate")] public string? PatientDateOfBirth { get; set; }
}

完成以上配置后，Swagger UI中该属性会显示指定的格式标识，自动生成的OpenAPI JSON文档里也会包含format: "dd.mm.yyyy"的字段。

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