.net core 使用Swagger显示模型注释与API注释不全问题(.net 6/8)

使用.net core 6/8创建项目的时候，默认会在Program.cs中引用Swagger服务，这个是众所周知的事情。但运行后会发现这个文档略显简单，甚至可能连基本的注释都没有。这种情况下，需要我们手动的去设置一些文档的配置来实现我们想要的一些文档说明。

一、文档说明

在Program.cs文档中，最上方都是加入的一些第三方中间件服务，若是框架自动引用的Swagger组件，此处应该有一行代码为：

builder.Services.AddSwaggerGen(); //添加Swagger服务

接下来就需要对这个方法做一些改变：

builder.Services.AddSwaggerGen(config =>
{
    config.SwaggerDoc("v1", new OpenApiInfo()
    {
        Title = "API接口文档名称", //API接口文档名称，见下图注1
        Description = "API接口文档的说明", //API接口文档的说明，见下图注2
        Version = "1.0", //当前API接口文档版本，见下图注3
        TermsOfService = new Uri("https://www.baidu.com"), //API使用条款文档链接，见下图注4
        Contact = new OpenApiContact() //创建API作者联系方式，用来展示API文档创建人联系信息
        {
            Email = "xxxxxxxxx@qq.com",           //作者邮箱，见下图注6
            Name = "月落",                         //作者名字，与邮箱和个人主页一同出现
            Url = new Uri("https://www.baidu.com") //作者个人主页，见下图注5
        }
    });
    //获取程序集所在目录，一般为根目录
    string? basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
    //获取API项目所生成的XML文档路径
    string? apiPath = $"{basePath}\\FilmManagementSystemAPI.xml";
    获取API模型项目实体类所生成的XML文档路径
    string? modelPath = $"{basePath}\\FilmManagementSystemAPI.Model.xml";
    //将API文档所生成的XML路径包含进去
    config.IncludeXmlComments(apiPath);
    //将API模型项所生成的XML路径包含进去
    config.IncludeXmlComments(modelPath);
});

以上代码中有一个点需要注意，即：

config.SwaggerDoc("v1", new OpenApiInfo()
{
    ……
});

中第一个参数，这个参数对应的是json文件路径，如果写别的将报错：

当然若是你自己有这个路径就没有这个问题了！

二、生成XML文件

以上操作全部完成后，还得继续生成XML文件，才能在运行的Swagger上看到，方法比较简单，右键项目，选择属性，点击生成目录下的输出项目，勾选生成XML文档文件（或生成包含API文档的文件）即可。

重新生成后运行项目将会在Swagger中出现所要看到的注释。