.NET Core .NET 6 为Swagger添加注释

生成xml文件

选择需要生成注释文件（xml文件）的项目，右键编辑项目文件.csproj，设置GenerateDocumentationFile=true

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

这里我为DotNet6WebAPI.csproj项目设置GenerateDocumentationFile，生成DotNet6WebAPI.xml文件 注释内容：为StudentController和StudentDto添加注释，生成的xml文件如下：

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>DotNet6WebAPI</name>
    </assembly>
    <members>
        <member name="M:DotNet6WebAPI.Controllers.StudentController.Get(System.String)">
            <summary>
            Search student information by id(根据id查询学生信息)
            </summary>
            <param name="id"></param>
            <returns></returns>
        </member>
        <member name="P:DotNet6WebAPI.Dtos.Students.StudentDto.Id">
            <summary>
            id
            </summary>
        </member>
        <member name="P:DotNet6WebAPI.Dtos.Students.StudentDto.Name">
            <summary>
            name(名称)
            </summary>
        </member>
        <member name="P:DotNet6WebAPI.Dtos.Students.StudentDto.Age">
            <summary>
            age(年龄)
            </summary>
        </member>
        <member name="P:DotNet6WebAPI.Dtos.Students.StudentDto.PhoneNumber">
            <summary>
            phone number(电话号码)
            </summary>
        </member>
    </members>
</doc>

设置Swagger

修改Program.cs的AddSwaggerGen()方法

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "Dotnet 6 demo Api",
        Version = "v1",
        Description = "description."
    });

    // Set the comments path for the Swagger JSON and UI.
    // 设置注释
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

效果

同时，schema文件也有了注释（节选）

{
    "schemas": {
      "StudentDto": {
        "required": [
          "id",
          "name"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "id"
          },
          "name": {
            "maxLength": 50,
            "minLength": 0,
            "type": "string",
            "description": "name(名称)"
          },
          "age": {
            "type": "integer",
            "description": "age(年龄)",
            "format": "int32"
          },
          "phoneNumber": {
            "type": "string",
            "description": "phone number(电话号码)",
            "nullable": true
          }
        },
        "additionalProperties": false
      }
    }
}

为枚举值添加注释

参考Description of the Enumeration Members in Swashbuckle，可以写一个EnumTypesSchemaFilter实现ISchemaFilter

public class EnumTypesSchemaFilter : ISchemaFilter
{
    private readonly XDocument _xmlComments;

    public EnumTypesSchemaFilter(string xmlPath)
    {
        if (File.Exists(xmlPath))
        {
            _xmlComments = XDocument.Load(xmlPath);
        }
    }

    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (_xmlComments == null) return;

        if (schema.Enum != null && schema.Enum.Count > 0 &&
            context.Type != null && context.Type.IsEnum)
        {
            schema.Description += "<p>Members:</p><ul>";

            var fullTypeName = context.Type.FullName;

            foreach (var enumMemberName in schema.Enum.OfType<OpenApiString>().
                        Select(v => v.Value))
            {
                var fullEnumMemberName = $"F:{fullTypeName}.{enumMemberName}";

                var enumMemberComments = _xmlComments.Descendants("member")
                    .FirstOrDefault(m => m.Attribute("name").Value.Equals
                    (fullEnumMemberName, StringComparison.OrdinalIgnoreCase));

                if (enumMemberComments == null) continue;

                var summary = enumMemberComments.Descendants("summary").FirstOrDefault();

                if (summary == null) continue;

                schema.Description += $"<li><i>{enumMemberName}</i> - {summary.Value.Trim()}</li> ";
            }
            schema.Description += "</ul>";
        }
    }
}

然后进行配置

var xmlFile2 = $"DotNet6WebAPI.Domain.xml";
var xmlPath2 = Path.Combine(AppContext.BaseDirectory, xmlFile2);
c.IncludeXmlComments(xmlPath2);
c.SchemaFilter<EnumTypesSchemaFilter>(xmlPath2);

即可在Swagger中显示每项枚举值的注释

示例代码

DotNet6WebAPI.csproj
Program.cs
StudentDto.cs
TeacherLevel

参考资料

How do you add a swagger comment to the "Request and Response Model"?
Description of the Enumeration Members in Swashbuckle